镜像配置不等于标准化交付，真正卡住交付的是配置未落进实际运行用户环境、缓存路径错配为vendor/、关键参数被项目级prefer-source:true等设置覆盖；三者齐备才能保障CI构建稳定高效。
镜像配置本身不等于标准化交付，真正卡住交付的往往是配置没落进实际运行环境、缓存路径错配、或参数被项目级设置悄悄覆盖——这三处不处理，CI 构建照样超时、本地 vendor 依旧报 Class not found。
composer config -g repo.packagist 为什么在 CI 里总不生效
CI 容器里执行命令的用户（如 GitHub Actions 的 runner、GitLab CI 的 gitlab-runner）和你本地 sudo composer config -g 写入的用户（root）不是同一个。配置写进了 /root/.composer/config.json，但 runner 用户读的是自己的 /home/runner/.composer/config.json，根本看不到。
- 先确认实际用户：
whoami或查 CI 日志里的 UID - 针对性执行（别加
sudo）：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 验证是否写入：
composer config -g repo.packagist输出必须是完整 JSON，比如{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}，空、null或仍显示packagist.org就是失败 - 拼写错误会静默失败：写成
repos.packagist（多一个 s）、repo.packagist.org或漏掉composertype 值，都不生效且无提示
项目级配置比全局更可靠，尤其在 Docker 和团队协作中
在项目根目录下运行 composer config repo.packagist composer https://mirrors.aliyun.com/composer/，会自动向 composer.json 的 repositories 字段追加 packagist 条目。它不覆盖已有私有源，配置随 Git 提交，新人拉完代码就能直接 composer install，无需额外 setup 步骤。
- 如果
composer.json已有"repositories": {}（空对象），命令能安全 merge；但如果是"repositories": []（数组），会报错，得先手动改成对象 - 别手写
"packagist.org": false—— 这会彻底关掉默认源，镜像一不可用，composer install直接失败 - Dockerfile 中避免用
RUN composer config -g：多数 PHP 基础镜像没初始化~/.composer目录，该命令会静默失败；改用项目级配置或--repository-url参数
--no-dev --prefer-dist 这些参数为什么有时没用
--prefer-dist 被项目级 "prefer-source": true 强制覆盖是最常见原因。只要 composer.json 里存在这个字段，Composer 就一定走 Git clone，而 CI 环境通常没配 SSH 密钥或禁用了 Git 协议，结果就是卡死在 Cloning into 'xxx'。
立即学习“PHP免费学习笔记（深入）”；
- 检查：
grep -n "prefer-source" composer.json - 修复：
composer config --unset prefer-source或手动删掉该行 - 私有包只提供 Git 地址、没发布 dist 包时，
--prefer-dist会直接报Could not find a matching version of package xxx，此时必须去掉该参数 -
--no-dev在 CI 中必须加：它跳过require-dev解析，减少依赖树复杂度，显著缩短Resolving dependencies阶段耗时
缓存 vendor/ 是交付中最危险的操作
缓存 vendor/ 目录看似省时间，实则埋雷。不同 PHP 版本、扩展启用状态、甚至操作系统（Linux vs macOS）生成的 autoloader 不兼容。CI 缓存了 PHP 8.2 下生成的 vendor/，但某次构建用了 PHP 8.3，就可能爆出 Class not found 或 Cannot declare class。
- 正确缓存路径是
~/.composer/cache（Composer 自身缓存），不是vendor/ - CI 脚本里应明确清理旧
vendor/：rm -rf vendor && composer install --no-dev --prefer-dist - 若要用缓存加速，只缓存 Composer 的 dist 包缓存目录，并确保每次构建前
composer clear-cache后再装（尤其换镜像后）
标准化交付的关键不在“快”，而在“稳”：镜像 URL 末尾的斜杠、repo.packagist 的拼写、vendor/ 是否参与缓存——这些细节一旦错位，交付产物就不可复现。最稳妥的做法，是把项目级镜像配置 + --no-dev --prefer-dist + 清理 vendor/ 写进 CI 脚本模板，而不是依赖全局配置或本地经验。
