唯一可靠方案是path仓库:主项目composer.json根级配相对路径repositories,本地包composer.json须声明"options": {"symlink": true}且name、version与require逐字匹配,改autoload后须手动执行composer dump-autoload -o,lock文件必须提交。

团队用 Composer 共享本地包,不按规范走,composer install 一跑就报 Could not find package,CI 构建直接挂掉——这不是偶然,是路径、版本、软链、lock 文件四者没对齐的必然结果。
path 仓库的 url 必须是项目根目录下的相对路径
Composer 的 repositories.type: "path" 不解析环境变量,也不接受绝对路径或上层路径。写错就等于没配,Composer 会静默跳过该仓库,转头去 Packagist 找包,然后失败。
- ✅ 正确:
"url": "packages/my-utils"(假设项目结构是./packages/my-utils/composer.json) - ❌ 错误:
"url": "/home/alex/my-utils"、"url": "${HOME}/my-utils"、"url": "../shared/my-utils" - ⚠️ 注意:
url不能以./开头;也不能跨出 Git 仓库边界——所有成员必须把共享包放在统一位置,比如全部放../shared-packages/,主项目统一配"url": "../shared-packages/my-utils"
symlink 生效的前提:被引用包自己声明 "options": {"symlink": true}
很多人在主项目的 repositories 里加 "options": {"symlink": true},完全无效。path 类型的软链控制权不在主项目,而在被引用的那个本地包自己的 composer.json 中。
- 必须在
packages/my-utils/composer.json里写:"options": {"symlink": true} - 这个配置只在
composer update vendor/name或全量composer update时生效;composer install不重建软链 - Windows 用户需开启“开发者模式”或管理员权限运行终端,否则 symlink 会退化为复制,改代码不生效
- 验证是否成功:
ls -la vendor/vendor/name应看到->指向源目录(Linux/macOS);Windows 下dir vendor\vendor\name应显示“快捷方式”
require 版本号必须和被引用包的 name + version 逐字匹配
path 包不是 bypass 版本校验的后门,它仍走完整依赖解析流程。name 拼错、version 字段缺失、或约束不兼容,都会导致解析失败。
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
- 被引用包的
composer.json必须有"name": "acme/utils"和"version": "1.0.x-dev"(不能省略version,Composer 2.5+ 会直接拒绝加载) - 主项目
require必须写:"acme/utils": "1.0.x-dev",不能写"^1.0"或"dev-main"(除非被引用包也叫"version": "dev-main") - 大小写、vendor 名、斜杠方向必须完全一致——
acme/utils和Acme/utils是两个包
composer.lock 必须提交,且 vendor/ 必须忽略
有人觉得 “path 包是本地的,lock 文件无所谓”,这是最危险的认知偏差。lock 文件决定了每个成员和 CI 环境最终装进 vendor/ 的到底是 symlink 还是副本、是哪个 commit、autoload 是否命中——它就是协作的事实来源。
-
composer.lock必须git add并提交;vendor/必须出现在.gitignore里 - 首次引入 path 包,必须运行
composer update acme/utils(不是install),否则 lock 文件不会记录该包的真实路径和 symlink 状态 - 改了被引用包的
autoload映射(比如新增 PSR-4 命名空间),必须手动在主项目执行composer dump-autoload -o,否则类找不到
最容易被忽略的一点:虚拟包(replace/provide)如果声明在主项目而非实际发布的包中,对其他下游项目完全无效;而它的影响又是隐式的、跨项目的——等你在另一个服务里发现日志类突然加载失败,回溯起来要花半天。










