必须在主项目composer.json根级配置repositories数组，且本地包name、路径、版本须严格匹配，否则Composer静默跳过；需用相对路径、合法JSON、显式dev-main版本、本地包内设symlink并管理员权限执行update。
直接在项目里用 path 类型仓库 + composer install 就能装本地包，不需要 publish、不走网络、不依赖镜像源——这是最轻量、最可控的私有化部署方式。
为什么不能只改 repositories 就生效？
Composer 解析 repositories 时要求：必须是数组、每个条目必须有合法 type、url 必须指向一个可读的本地路径（不是 URL）。常见错误包括：
- 把
repositories写成对象而非数组，例如"repositories": {"type":"path",...}→ 报错Invalid repository type或静默忽略 -
url指向不存在的路径，或权限不足（如 SELinux 限制），composer update会跳过该源且不报错 - 没清
composer.lock和vendor/，旧缓存可能让新配置不触发重安装
path 类型仓库怎么写才可靠？
在项目根目录的 composer.json 中，repositories 数组第一项必须是本地路径声明：
{
"repositories": [
{
"type": "path",
"url": "../my-private-package"
}
],
"require": {
"acme/utils": "*"
}
}
注意要点：
-
url是相对路径，从项目根目录算起；支持../、./packages/foo，但不能是绝对路径（如/home/user/pkg） - 本地包目录下必须有有效的
composer.json，且其中name字段（如"acme/utils"）要和require中一致 -
"*"版本号会匹配本地包的version字段或 Git 分支标签；若本地包无version，Composer 默认用dev-main（或dev-master） - 本地包的
type推荐设为library，避免被误判为project导致自动加载异常
执行安装时哪些命令不能乱用？
composer install 是唯一安全的离线安装命令；composer update 会重新解析所有源（包括尝试连 packagist.org），即使你只改了本地包版本也会失败。
- 首次安装前，确保
vendor/为空或已删除，否则旧包残留可能引发 autoloader 冲突 - 不要加
--no-dev除非确认本地包不依赖require-dev，否则可能漏装测试工具类 - 如果本地包用了
autoload的psr-4，检查其composer.json中命名空间路径是否正确（如"Acme\Utils\": "src/"），否则类找不到 - CI/CD 环境中，需确保构建机上该本地路径真实存在且可读——Docker 构建时容易因挂载路径不一致导致失败
最关键的细节：本地包路径一旦写进 composer.json，就绑定了开发机的目录结构。团队协作时，要么统一约定路径（如都放 ../packages/xxx），要么用 CI 脚本在构建前软链接到固定位置。没人会帮你自动 resolve 相对路径。
