Composer path仓库默认不复制本地包，因其仅创建软链接（symlink），而非硬复制；根本原因是path类型仓库强制启用symlink且无“复制”开关，需改用package类型仓库并配置dist字段才能实现真正复制。
Composer path仓库为什么不会自动复制本地包
默认情况下，path 类型仓库只是软链接（symlink）到本地目录，不是复制。这在开发中方便实时调试，但上线或 CI 环境里常因 symlink 失效、权限问题或容器挂载限制导致 vendor/autoload.php 找不到类，报 Class not found 错误。
根本原因：Composer 的 path 仓库默认启用 symlink: true，且仅当目标路径存在、有读写权限、且未显式禁用 symlink 时才创建链接——它压根不提供“复制”开关。
用 composer config --global path-repository-xxx.type path 不起作用
很多人试过全局或项目级配置 path 仓库类型，以为能控制行为，但没用：type: path 只声明仓库类型，不控制安装策略。真正决定是否复制的，是包自身的 composer.json 中的 archive 或 dist 配置，而 path 包根本不走 dist 流程。
可行路径只有两个：
- 改用
package类型仓库 + 手动定义dist（适合稳定发布版） - 保留
path类型，但通过composer install --no-dev --prefer-dist强制跳过 symlink —— 这招其实无效，因为path包无视--prefer-dist - 真正有效的办法：在本地包的
composer.json里加"archive": {"exclude": ["/tests", "/docs"]}并配合composer archive手动打包，再用package仓库引用 zip
最简可行方案：用 package 仓库替代 path，并指定 dist
这是唯一能确保“复制”的方式——让 Composer 把包当成远程 zip 下载解压，自然就是硬复制。
操作步骤：
- 在本地包根目录运行
composer archive --format=zip --file=dist/my-package-1.0.0.zip - 在项目
composer.json的repositories中添加：
{
"type": "package",
"package": {
"name": "vendor/my-package",
"version": "1.0.0",
"dist": {
"url": "./dist/my-package-1.0.0.zip",
"type": "zip"
},
"autoload": { "psr-4": { "Vendor\MyPackage\": "src/" } }
}
}
注意：url 必须是相对路径（从项目根开始），且 dist 字段必须存在；否则 Composer 仍会尝试 symlink。
CI/CD 中要注意的硬编码陷阱
上面方案在本地跑得通，但推到 CI 时容易出错：比如 ./dist/my-package-1.0.0.zip 在构建机上根本不存在，或者权限不足无法读取。
安全做法：
- 把 zip 放进 Git LFS 或私有对象存储（如 S3），用真实 HTTP URL 替代
./dist/... - 在 CI 脚本里先
composer archive再composer install，但要确保archive命令在 vendor 包已就位后执行（即不能在composer install之前） - 永远不要在
repositories里写绝对路径或环境变量（如$HOME/dist/...），Composer 不解析它们
最易忽略的一点：如果你用的是 Composer 2.2+，archive 命令默认排除 .git 和 vendor，但不会自动排除 node_modules——若包里混了前端资源，zip 会巨大且可能触发超时。手动加 --exclude=node_modules 更稳妥。
