必须用path类型仓库配合"symlink":true和dev-main版本约束，否则默认复制导致代码修改不生效；上线前须移除repositories并运行composer update --lock刷新lock文件。
直接用 path 类型仓库引入本地包，不是“优雅”的问题，而是“危险”和“不可靠”的问题——它绕过 Composer 的依赖解析与版本锁定机制，极易导致团队协作失败、CI 构建不一致、甚至生产环境静默降级。
为什么 path 仓库在 composer.json 中不推荐直接写死
你可能见过这样的配置：
{
"repositories": [
{
"type": "path",
"url": "../my-package"
}
],
"require": {
"acme/my-package": "*"
}
}
这看似方便，但实际埋了多个雷：
-
path仓库不参与版本约束计算，*会始终取本地目录最新代码，哪怕你已提交了v1.2.0tag，Composer 也完全无视 - CI/CD 环境中
../my-package路径根本不存在，构建直接失败 - 其他协作者 clone 主项目后，不会自动 clone 或同步本地包，
composer install报错或静默跳过 - 一旦你本地包有未提交的修改，
composer update会把脏状态“污染”进主项目的vendor/
真正可落地的本地开发方案：用 path + dev-main 显式控制
目标是：开发时能实时调试本地包，发布时无缝切回 Packagist 正式源。关键不是禁用 path，而是把它变成“临时开关”：
- 只在
composer.json的config段启用path，而非repositories—— 这样它仅影响require中明确指定dev-分支的包 - 本地包的
composer.json必须声明"minimum-stability": "dev"和"prefer-stable": true，避免意外拉取不稳定版本 - 主项目 require 时必须写死分支名，例如：
"acme/my-package": "dev-main"（不是*或dev-master） - 确保本地包根目录存在
composer.json且版本号字段（version）为空或设为dev-main，否则 Composer 会忽略该 path
最终生效的最小配置示例：
{
"config": {
"preferred-install": "dist",
"sort-packages": true,
"allow-plugins": {
"dealerdirect/phpcodesniffer-composer-installer": true
}
},
"require": {
"acme/my-package": "dev-main"
},
"repositories": [
{
"type": "path",
"url": "../my-package",
"options": {
"symlink": true
}
}
]
}
symlink 选项不是可选，而是必须开启
不加 "symlink": true，Composer 默认会把本地包整个复制进 vendor/，导致：
- 你在
../my-package中改代码，vendor/acme/my-package不同步 - 反复
composer update触发无意义的文件拷贝，拖慢开发流 - IDE 跳转、Xdebug 断点全部指向
vendor/副本，而非真实源码
开启 symlink 后，vendor/acme/my-package 是个符号链接，指向你的本地目录，改一处、全链路生效。注意：Windows 用户需以管理员权限运行终端首次启用 symlink，否则报错 symlink(): Operation not permitted。
上线前必须删掉 path 仓库并锁定正式版本
上线部署脚本里如果还留着 path 配置，CI 会因路径不存在而失败；更糟的是，若 CI 环境恰好有同名目录，它会偷偷加载未测试的本地代码。
- 上线前执行：
composer remove acme/my-package && composer require acme/my-package:^1.2（用真实稳定版号） - 确认
composer.json的repositories数组已清空，或只剩 Packagist 官方源 - 检查
composer.lock中acme/my-package的source字段是否为"type": "git"且url指向 GitHub/GitLab，而非"/absolute/path/to/my-package"
最易被忽略的一点：composer.lock 文件本身不会因删掉 repositories 自动更新，必须显式运行 composer update --lock 或重新 composer install 才能刷新 source 记录。
