Composer 依赖管理 #

composer.json 完全解析 #

文件结构 #

json

{
    "name": "vendor/project",
    "description": "项目描述",
    "type": "project",
    "license": "MIT",
    "keywords": ["php", "package"],
    "authors": [
        {
            "name": "Your Name",
            "email": "you@example.com",
            "homepage": "https://example.com",
            "role": "Developer"
        }
    ],
    "require": {},
    "require-dev": {},
    "autoload": {},
    "autoload-dev": {},
    "scripts": {},
    "config": {},
    "extra": {}
}

基本信息字段 #

name（包名） #

包名格式为 供应商/项目名：

json

{
    "name": "laravel/framework"
}

命名规则：

必须小写
供应商名和项目名用 / 分隔
可以包含字母、数字、连字符、下划线
不允许空格和特殊字符

description（描述） #

json

{
    "description": "The Laravel Framework."
}

type（类型） #

json

{
    "type": "library"
}

可用类型：

类型	说明
`library`	默认类型，PHP 库
`project`	项目应用
`metapackage`	元包，只包含依赖
`composer-plugin`	Composer 插件

license（许可证） #

json

{
    "license": "MIT"
}

常用许可证：

许可证	说明
MIT	MIT 许可证
Apache-2.0	Apache 许可证 2.0
BSD-2-Clause	BSD 2 条款许可证
BSD-3-Clause	BSD 3 条款许可证
GPL-2.0-only	GPL 2.0
GPL-3.0-only	GPL 3.0
LGPL-2.1-only	LGPL 2.1
LGPL-3.0-only	LGPL 3.0

keywords（关键词） #

json

{
    "keywords": ["framework", "laravel", "php"]
}

authors（作者） #

json

{
    "authors": [
        {
            "name": "Taylor Otwell",
            "email": "taylor@laravel.com",
            "homepage": "https://laravel.com",
            "role": "Developer"
        }
    ]
}

support（支持信息） #

json

{
    "support": {
        "email": "support@example.com",
        "issues": "https://github.com/vendor/project/issues",
        "forum": "https://forum.example.com",
        "wiki": "https://wiki.example.com",
        "irc": "irc://irc.example.com/channel",
        "source": "https://github.com/vendor/project",
        "docs": "https://docs.example.com",
        "rss": "https://blog.example.com/rss"
    }
}

依赖类型 #

require（生产依赖） #

生产环境必需的依赖：

json

{
    "require": {
        "php": "^8.1",
        "ext-json": "*",
        "laravel/framework": "^10.0",
        "guzzlehttp/guzzle": "^7.0"
    }
}

require-dev（开发依赖） #

仅开发环境需要的依赖：

json

{
    "require-dev": {
        "phpunit/phpunit": "^10.0",
        "mockery/mockery": "^1.0",
        "laravel/pint": "^1.0",
        "spatie/laravel-ignition": "^2.0"
    }
}

依赖类型对比 #

类型	安装时机	包含在发布中	典型用途
require	始终安装	是	框架、库、工具
require-dev	默认安装	否	测试、调试工具

平台依赖 #

PHP 版本 #

json

{
    "require": {
        "php": "^8.1",
        "php": ">=8.1",
        "php": "8.1.*",
        "php": "^8.1.0"
    }
}

PHP 扩展 #

json

{
    "require": {
        "ext-json": "*",
        "ext-mbstring": "*",
        "ext-pdo": "*",
        "ext-xml": "*",
        "ext-curl": "*"
    }
}

Lib 扩展 #

json

{
    "require": {
        "lib-curl": "*",
        "lib-openssl": "*"
    }
}

版本约束详解 #

语义化版本 #

语义化版本格式：MAJOR.MINOR.PATCH

text

MAJOR - 不兼容的 API 变更
MINOR - 向后兼容的功能新增
PATCH - 向后兼容的 bug 修复

版本约束类型 #

1. 精确版本 #

json

{
    "require": {
        "monolog/monolog": "1.2.3"
    }
}

2. 范围版本 #

json

{
    "require": {
        "package/name": ">=1.0",
        "package/name": ">=1.0 <2.0",
        "package/name": ">=1.0,<=2.0",
        "package/name": ">1.0 <2.0",
        "package/name": "<=2.0"
    }
}

3. 波浪号约束 (~) #

json

{
    "require": {
        "package/name": "~1.2.3",
        "package/name": "~1.2"
    }
}

约束	等价于	允许的版本
`~1.2.3`	`>=1.2.3 <1.3.0`	1.2.3, 1.2.4, 1.2.99
`~1.2`	`>=1.2.0 <2.0.0`	1.2.0, 1.3.0, 1.99.0
`~0.3`	`>=0.3.0 <0.4.0`	0.3.0, 0.3.1, 0.3.99

4. 插入号约束 (^) #

json

{
    "require": {
        "package/name": "^1.2.3",
        "package/name": "^0.3.2"
    }
}

约束	等价于	允许的版本
`^1.2.3`	`>=1.2.3 <2.0.0`	1.2.3, 1.3.0, 1.99.0
`^0.3.2`	`>=0.3.2 <0.4.0`	0.3.2, 0.3.3, 0.3.99
`^0.0.3`	`>=0.0.3 <0.0.4`	0.0.3

5. 通配符 (*) #

json

{
    "require": {
        "package/name": "1.2.*",
        "package/name": "1.*",
        "package/name": "*"
    }
}

6. 或逻辑 (||) #

json

{
    "require": {
        "package/name": ">=1.0 <1.1 || >=1.2",
        "package/name": "^1.0 || ^2.0"
    }
}

7. 连字符范围 (-) #

json

{
    "require": {
        "package/name": "1.0.0 - 2.0.0"
    }
}

等价于：>=1.0.0 <=2.0.0

版本约束最佳实践 #

json

{
    "require": {
        "php": "^8.1",
        "laravel/framework": "^10.0",
        "guzzlehttp/guzzle": "^7.5",
        "monolog/monolog": "^2.0",
        "nesbot/carbon": "^2.0"
    },
    "require-dev": {
        "phpunit/phpunit": "^10.0",
        "mockery/mockery": "^1.5"
    }
}

稳定性标志 #

minimum-stability #

控制依赖的最低稳定性：

json

{
    "minimum-stability": "stable"
}

可用值：

值	说明
`stable`	只使用稳定版本（默认）
`RC`	包含候选发布版本
`beta`	包含测试版本
`alpha`	包含 alpha 版本
`dev`	包含开发版本

prefer-stable #

优先选择稳定版本：

json

{
    "minimum-stability": "dev",
    "prefer-stable": true
}

稳定性标志 #

为单个包指定稳定性：

json

{
    "require": {
        "monolog/monolog": "dev-master",
        "some/package": "1.0.0-beta@beta",
        "another/package": "1.0.0-alpha@alpha"
    }
}

稳定性级别 #

text

stable (最稳定)
    │
    ├── RC (Release Candidate)
    │
    ├── beta
    │
    ├── alpha
    │
    └── dev (最不稳定)

composer.lock 详解 #

什么是 composer.lock？ #

composer.lock 是依赖锁定文件，记录了实际安装的每个包的精确版本：

json

{
    "_readme": [
        "This file locks the dependencies of your project to a known state"
    ],
    "content-hash": "abc123...",
    "packages": [
        {
            "name": "monolog/monolog",
            "version": "2.9.2",
            "source": {
                "type": "git",
                "url": "https://github.com/Seldaek/monolog.git",
                "reference": "e3798b..."
            },
            "dist": {
                "type": "zip",
                "url": "https://api.github.com/repos/Seldaek/monolog/zipball/e3798b...",
                "reference": "e3798b...",
                "shasum": ""
            },
            "require": {
                "php": ">=7.2",
                "psr/log": "^1.0.1 || ^2.0 || ^3.0"
            },
            "time": "2023-10-06T10:11:52+00:00",
            "type": "library",
            "installation-source": "dist",
            "autoload": {
                "psr-4": {
                    "Monolog\\": "src/Monolog"
                }
            }
        }
    ],
    "packages-dev": [],
    "aliases": [],
    "minimum-stability": "stable",
    "stability-flags": [],
    "prefer-stable": true,
    "prefer-lowest": false
}

lock 文件的作用 #

text

开发环境                          生产环境
    │                               │
    ├── composer install            ├── composer install
    │   └── 读取 composer.json      │   └── 读取 composer.lock
    │                               │
    ├── 生成 composer.lock          ├── 按锁定版本安装
    │   └── 记录精确版本            │   └── 版本完全一致
    │                               │
    └── 提交到版本控制              └── 部署成功

lock 文件管理 #

bash

# 更新 lock 文件
composer update

# 更新特定包的 lock
composer update package/name

# 检查 lock 文件是否与 json 同步
composer check-platform-reqs

# 验证 lock 文件
composer validate --strict

是否提交 composer.lock？ #

项目类型	是否提交	原因
应用项目	✅ 是	确保部署一致性
库项目	❌ 否	让使用者选择版本
库项目（应用依赖）	✅ 是	确保开发一致性

依赖解析 #

依赖解析流程 #

text

composer.json
    │
    ├── 解析 require
    │   └── 获取版本约束
    │
    ├── 查询 Packagist
    │   └── 获取可用版本
    │
    ├── 解析依赖树
    │   ├── 递归解析子依赖
    │   └── 检查版本兼容性
    │
    ├── 解决冲突
    │   ├── 寻找兼容版本
    │   └── 必要时回溯
    │
    └── 生成 composer.lock
        └── 记录最终版本

依赖冲突解决 #

查看依赖树 #

bash

# 查看完整依赖树
composer show -t

# 查看特定包的依赖
composer show laravel/framework --tree

查找冲突原因 #

bash

# 查看为什么需要某个包
composer why vendor/package

# 查看为什么不能安装某个包
composer prohibits vendor/package 2.0

解决冲突 #

bash

# 更新所有依赖
composer update --with-all-dependencies

# 强制更新
composer update --with-all-dependencies --ignore-platform-reqs

仓库配置 #

Packagist（默认仓库） #

json

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://repo.packagist.org"
        }
    ]
}

私有仓库 #

VCS 仓库 #

json

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/company/private-package"
        }
    ]
}

Git 仓库 #

json

{
    "repositories": [
        {
            "type": "git",
            "url": "https://github.com/company/private-package.git"
        }
    ]
}

本地路径 #

json

{
    "repositories": [
        {
            "type": "path",
            "url": "../my-package"
        }
    ]
}

Satis 私有仓库 #

json

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://satis.example.com"
        }
    ]
}

禁用 Packagist #

json

{
    "repositories": [
        {
            "packagist.org": false
        }
    ]
}

配置选项 #

config 字段 #

json

{
    "config": {
        "platform": {
            "php": "8.1.0"
        },
        "preferred-install": "dist",
        "sort-packages": true,
        "optimize-autoloader": true,
        "classmap-authoritative": true,
        "apcu-autoloader": true,
        "process-timeout": 2000,
        "use-include-path": false,
        "github-protocols": ["https"],
        "gitlab-domains": ["gitlab.com"],
        "disable-tls": false,
        "secure-http": true,
        "cafile": "/path/to/cacert.pem",
        "capath": "/path/to/ca-dir",
        "http-basic": {
            "example.org": {
                "username": "user",
                "password": "pass"
            }
        },
        "store-auths": true,
        "github-oauth": {
            "github.com": "token"
        },
        "gitlab-oauth": {
            "gitlab.com": "token"
        },
        "bearer": {
            "example.org": "token"
        }
    }
}

常用配置说明 #

配置项	说明	默认值
`preferred-install`	安装方式	`dist`
`sort-packages`	排序包	`false`
`optimize-autoloader`	优化自动加载	`false`
`classmap-authoritative`	权威类映射	`false`
`apcu-autoloader`	APCu 缓存	`false`
`process-timeout`	进程超时(秒)	`300`
`secure-http`	HTTPS 安全	`true`

平台配置 #

模拟平台包：

json

{
    "config": {
        "platform": {
            "php": "8.1.0",
            "ext-something": "1.0.0"
        }
    }
}

其他字段 #

suggest（建议） #

建议安装的可选包：

json

{
    "suggest": {
        "ext-ctype": "Required for faster ASCII validation",
        "ext-iconv": "Required for faster character encoding conversion",
        "ext-mbstring": "Required for multibyte string handling"
    }
}

conflict（冲突） #

声明冲突的包版本：

json

{
    "conflict": {
        "laravel/framework": "<9.0",
        "symfony/console": "<6.0"
    }
}

replace（替换） #

替换其他包：

json

{
    "replace": {
        "monolog/monolog": "self.version"
    }
}

provide（提供） #

声明提供的虚拟包：

json

{
    "provide": {
        "psr/log-implementation": "1.0|2.0|3.0"
    }
}

bin（可执行文件） #

声明可执行脚本：

json

{
    "bin": [
        "bin/my-script"
    ]
}

extra（额外信息） #

自定义额外信息：

json

{
    "extra": {
        "laravel": {
            "providers": [
                "App\\Providers\\MyServiceProvider"
            ]
        }
    }
}

下一步 #

现在你已经深入了解了依赖管理，接下来学习自动加载机制掌握 PHP 类的自动加载！