必须把配置写进项目级composer.json，因为全局配置不进git、ci读不到，无法保障协作一致性；如私有源、platform版本、repositories顺序等关键设置，必须在项目文件中显式声明并提交。
必须把配置写进项目级 composer.json，而不是靠 composer config --global 或口头约定——后者在 CI、新成员、分支切换时全失效。
为什么不能依赖全局配置（composer config --global）
全局配置是本地文件，不进 Git，CI 流水线根本读不到。比如你在本地执行了 composer config --global repositories.packagist.org url https://mirrors.aliyun.com/composer/，别人 clone 项目后运行 composer install 仍会 fallback 到官方源，私有包直接报 Could not find package。更麻烦的是：platform 配置写在全局里，就无法按项目差异化（A 项目要 PHP 8.1，B 项目还在 7.4）；dev 分支想用 snapshot 源，main 用 release 源——全局做不到。
项目级 composer.json 必须包含哪些字段
所有团队项目根目录的 composer.json 应统一包含以下内容，且提交到 Git：
-
"minimum-stability": "stable"和"prefer-stable": true，防止意外引入dev-包 -
"platform"显式声明目标环境 PHP 版本，例如{"php": "8.1.0"}，它只影响依赖解析，不装扩展，但能锁住兼容版本 -
"repositories"显式列出私有源和兜底的packagist.org，顺序很重要：私有源放前面，且必须保留packagist.org条目，否则 Composer 会跳过默认源 -
"config"中启用"sort-packages": true、"optimize-autoloader": true，减少合并冲突和提升加载性能 -
"scripts"定义标准化命令，如"test": "vendor/bin/phpunit"、"cs-fix": "php-cs-fixer fix"，避免成员记错路径或参数
如何让新项目开箱即用
不要让每个项目从零手写 composer.json：
- 维护一个内部模板仓库（如
company/composer-template），含预设的config、scripts、autoload和推荐插件（如dealerdirect/phpcodesniffer-composer-installer） - 提供
bin/setup-project脚本：自动复制模板、替换命名空间占位符、运行composer install并检查composer validate --strict - 在 README 顶部加一行安装说明：
curl -sS https://raw.githubusercontent.com/company/composer-template/main/bin/setup | bash，新成员一条命令起步
格式与结构一致性靠 composer-normalize 卡点
不同人编辑 composer.json 会导致缩进、键序、空行差异，Git 提交全是噪音。解决方案不是开会定规范，而是用工具强制：
- 项目内安装：
composer require --dev localheinz/composer-normalize（不推荐全局安装，版本易不一致） - 在
composer.json的scripts中加入："normalize": "composer normalize" - CI 中加检查：
composer normalize --dry-run || (echo '❌ composer.json not normalized' && exit 1) - Git pre-commit 钩子中跑
composer normalize --dry-run，失败则阻止提交
真正容易被忽略的是：没人会记得每次改完 composer.json 就手动跑一次 normalize，所以必须把它变成 Git 提交前的硬性门槛，而不是“建议步骤”。
