Composer 最佳实践 #

项目结构 #

标准项目结构 #

text

my-project/
├── app/                    # 应用代码
│   ├── Console/
│   ├── Http/
│   ├── Models/
│   └── Services/
├── config/                 # 配置文件
├── database/               # 数据库相关
│   ├── factories/
│   ├── migrations/
│   └── seeders/
├── public/                 # 公开目录
│   └── index.php
├── resources/              # 资源文件
├── storage/                # 存储目录
├── tests/                  # 测试代码
├── vendor/                 # 依赖目录（不提交）
├── .env                    # 环境变量（不提交）
├── .env.example            # 环境变量示例
├── .gitignore              # Git 忽略文件
├── composer.json           # Composer 配置
├── composer.lock           # 依赖锁定（提交）
└── README.md               # 项目说明

库项目结构 #

text

my-library/
├── src/                    # 源代码
│   ├── Exception/
│   ├── Model/
│   └── Service/
├── tests/                  # 测试代码
│   ├── Unit/
│   └── Feature/
├── docs/                   # 文档
├── examples/               # 示例
├── .gitignore
├── composer.json
├── phpunit.xml
├── CHANGELOG.md
├── LICENSE
└── README.md

.gitignore 配置 #

gitignore

# Composer
/vendor/
composer.lock

# 如果是应用项目，应该提交 composer.lock
# 如果是库项目，可以不提交 composer.lock

# 环境文件
.env
.env.local
.env.*.local

# IDE
.idea/
.vscode/
*.swp
*.swo
*~

# 系统文件
.DS_Store
Thumbs.db

# 日志
*.log
/storage/logs/*

# 缓存
/cache/*
/storage/framework/cache/*

composer.json 最佳实践 #

完整配置示例 #

json

{
    "name": "vendor/project",
    "description": "A brief description of the project",
    "type": "project",
    "license": "MIT",
    "keywords": ["php", "framework", "laravel"],
    "authors": [
        {
            "name": "Your Name",
            "email": "you@example.com",
            "homepage": "https://example.com",
            "role": "Developer"
        }
    ],
    "support": {
        "issues": "https://github.com/vendor/project/issues",
        "source": "https://github.com/vendor/project",
        "docs": "https://docs.example.com"
    },
    "require": {
        "php": "^8.1",
        "ext-json": "*",
        "ext-mbstring": "*",
        "laravel/framework": "^10.0",
        "guzzlehttp/guzzle": "^7.0"
    },
    "require-dev": {
        "phpunit/phpunit": "^10.0",
        "mockery/mockery": "^1.0",
        "phpstan/phpstan": "^1.0",
        "squizlabs/php_codesniffer": "^3.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "app/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Tests\\": "tests/"
        }
    },
    "scripts": {
        "test": "phpunit",
        "lint": "phpcs --standard=PSR12 src/",
        "stan": "phpstan analyse src/",
        "check": [
            "@lint",
            "@stan",
            "@test"
        ]
    },
    "scripts-descriptions": {
        "test": "Run the test suite",
        "lint": "Check code style",
        "stan": "Run static analysis",
        "check": "Run all checks"
    },
    "config": {
        "optimize-autoloader": true,
        "preferred-install": "dist",
        "sort-packages": true,
        "allow-plugins": {
            "php-http/discovery": true
        }
    },
    "minimum-stability": "stable",
    "prefer-stable": true,
    "extra": {
        "laravel": {
            "providers": [
                "App\\Providers\\MyServiceProvider"
            ]
        }
    }
}

库项目配置 #

json

{
    "name": "vendor/my-library",
    "description": "My awesome PHP library",
    "type": "library",
    "license": "MIT",
    "keywords": ["php", "library"],
    "authors": [
        {
            "name": "Your Name",
            "email": "you@example.com"
        }
    ],
    "require": {
        "php": "^8.1"
    },
    "require-dev": {
        "phpunit/phpunit": "^10.0",
        "phpstan/phpstan": "^1.0"
    },
    "autoload": {
        "psr-4": {
            "Vendor\\MyLibrary\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Vendor\\MyLibrary\\Tests\\": "tests/"
        }
    },
    "config": {
        "sort-packages": true
    },
    "extra": {
        "branch-alias": {
            "dev-main": "1.0-dev"
        }
    }
}

版本管理策略 #

语义化版本 #

text

MAJOR.MINOR.PATCH

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

版本约束选择 #

场景	推荐	示例
应用项目	精确版本或锁定	`composer.lock`
库项目	兼容版本	`^1.0`
开发依赖	兼容版本	`^10.0`

版本约束最佳实践 #

json

{
    "require": {
        "php": "^8.1",
        "laravel/framework": "^10.0",
        "guzzlehttp/guzzle": "^7.5",
        "monolog/monolog": "^2.0"
    }
}

不要使用 #

json

{
    "require": {
        "package/name": "*",     // ❌ 不推荐：任意版本
        "package/name": "dev-master",  // ❌ 不推荐：开发分支
        "package/name": ">=1.0"  // ⚠️ 谨慎使用：无上限
    }
}

依赖管理 #

选择依赖 #

评估标准 #

标准	检查项
活跃度	最近更新时间、issue 处理速度
稳定性	版本号、下载量、star 数
维护性	维护者数量、社区活跃度
安全性	已知漏洞、安全更新频率
许可证	是否符合项目要求

检查命令 #

bash

# 查看包信息
composer show vendor/package

# 查看依赖树
composer show -t

# 检查过时依赖
composer outdated

# 安全检查
composer audit

定期更新 #

bash

# 查看可更新的包
composer outdated

# 更新特定包
composer update vendor/package

# 更新所有依赖
composer update

# 更新并优化
composer update --optimize-autoloader

清理依赖 #

bash

# 移除不需要的依赖
composer remove vendor/package

# 清理未使用的依赖
composer install --no-dev

团队协作 #

统一配置 #

项目级 .npmrc 等效 #

创建 .composer 或在 composer.json 中配置：

json

{
    "config": {
        "platform": {
            "php": "8.1.0"
        },
        "preferred-install": "dist",
        "sort-packages": true
    }
}

统一镜像 #

bash

# 项目级配置
composer config repo.packagist composer https://mirrors.aliyun.com/composer/

composer.lock 管理 #

应用项目 #

bash

# ✅ 提交 composer.lock
git add composer.lock
git commit -m "Update dependencies"

# 团队成员同步
git pull
composer install

库项目 #

bash

# ⚠️ 可选提交 composer.lock
# 如果提交，有助于开发一致性
# 如果不提交，让使用者选择版本

冲突解决 #

bash

# composer.lock 冲突时
git checkout --theirs composer.lock
composer install

# 或重新生成
rm composer.lock
composer update

安全考虑 #

依赖安全 #

bash

# 检查已知漏洞
composer audit

# 检查并显示详细报告
composer audit --format=json

# 更新有漏洞的依赖
composer update vendor/package

配置安全 #

json

{
    "config": {
        "secure-http": true,
        "disable-tls": false,
        "cafile": "/path/to/cacert.pem"
    }
}

许可证检查 #

bash

# 查看所有依赖的许可证
composer licenses

# 检查许可证兼容性
composer licenses --no-dev

私有包安全 #

json

{
    "config": {
        "http-basic": {
            "private.example.com": {
                "username": "user",
                "password": "pass"
            }
        }
    }
}

使用环境变量：

bash

export COMPOSER_AUTH='{"http-basic":{"private.example.com":{"username":"user","password":"pass"}}}'

性能优化 #

开发环境 #

bash

# 快速安装
composer install --prefer-dist

# 使用缓存
# Composer 默认使用缓存

生产环境 #

bash

# 完整优化命令
composer install \
    --no-dev \
    --optimize-autoloader \
    --classmap-authoritative \
    --apcu-autoloader \
    --no-interaction \
    --no-progress \
    --prefer-dist

CI/CD 环境 #

bash

# 使用 ci 命令（Composer 2.x）
composer ci

# 或
composer install \
    --no-dev \
    --optimize-autoloader \
    --no-interaction \
    --no-progress \
    --prefer-dist

发布包 #

准备发布 #

1. 检查 composer.json #

bash

composer validate --strict

2. 确保测试通过 #

bash

composer test
composer stan

3. 更新版本 #

bash

# 使用 git tag
git tag v1.0.0
git push --tags

# 或使用 composer version
composer config version 1.0.0

发布到 Packagist #

创建 GitHub 仓库
登录 Packagist
提交包 URL
配置 GitHub Webhook 自动更新

版本发布流程 #

text

开发新功能
    │
    ├── 创建分支
    │   └── feature/new-feature
    │
    ├── 开发完成
    │   └── 合并到 main
    │
    ├── 更新 CHANGELOG
    │
    ├── 创建标签
    │   └── git tag v1.1.0
    │
    └── 推送标签
        └── Packagist 自动更新

常见问题解决 #

依赖冲突 #

bash

# 查看冲突
composer why-not vendor/package 2.0

# 解决冲突
composer update --with-all-dependencies

# 或手动指定版本
composer require vendor/package:^2.0

内存不足 #

bash

# 临时增加内存
COMPOSER_MEMORY_LIMIT=-1 composer update

# 或修改 php.ini
memory_limit = -1

网络问题 #

bash

# 使用镜像
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

# 增加超时
COMPOSER_PROCESS_TIMEOUT=600 composer install

缓存问题 #

bash

# 清理缓存
composer clear-cache

# 重新安装
rm -rf vendor/
composer install

检查清单 #

新项目检查清单 #

[ ] 正确配置 composer.json
[ ] 设置 PHP 版本要求
[ ] 配置自动加载
[ ] 添加 .gitignore
[ ] 配置脚本
[ ] 设置镜像（如需要）

发布前检查清单 #

[ ] 验证 composer.json
[ ] 运行测试
[ ] 运行静态分析
[ ] 更新 CHANGELOG
[ ] 检查许可证
[ ] 创建版本标签

部署前检查清单 #

[ ] 使用 composer install 而非 update
[ ] 使用 --no-dev 跳过开发依赖
[ ] 优化自动加载
[ ] 检查平台要求
[ ] 运行安全检查

总结 #

核心原则 #

版本锁定：应用项目始终提交 composer.lock
语义化版本：使用 ^ 约束，遵循语义化版本
定期更新：定期更新依赖，修复安全漏洞
安全检查：部署前运行安全检查
优化性能：生产环境优化自动加载

命令速查 #

场景	命令
安装依赖	`composer install`
更新依赖	`composer update`
添加依赖	`composer require vendor/package`
移除依赖	`composer remove vendor/package`
查看信息	`composer show vendor/package`
安全检查	`composer audit`
优化加载	`composer dump-autoload -o`
验证配置	`composer validate`

恭喜你完成了 Composer 完全指南的学习！现在你已经从新手成长为 Composer 专家，可以在项目中高效地使用 Composer 管理依赖了。