主项目 composer.json 必须在根级 repositories 数组中显式声明 type 为 "path" 的仓库,url 用 ./ 或 ../ 开头的相对路径指向含合法 composer.json 的目录,且本地包自身需配置 "options": {"symlink": true} 并严格匹配 name 与 version。

主项目 composer.json 的 repositories 必须显式声明 path 类型
Composer 不会自动扫描同级目录或子目录下的包,必须在主项目根目录的 composer.json 顶层手动加 repositories 字段,且不能嵌套在 require、config 或 extra 里。
常见错误写法:"repositories": {"type": "path", "url": "my-package"}(缺 ./ 前缀)、"url": "/abs/path"(绝对路径)、"url": "file://..."(协议前缀)——全部静默失效。
-
type必须是"path",不是"package"或空值 -
url必须以./或../开头,指向一个**含composer.json的目录**(不能是文件,也不能以/结尾) - 必须加
"options": {"symlink": true},否则 Windows 默认 fallback 到 copy 模式,改代码不生效
本地包 composer.json 的 name 和 version 要严格匹配
主项目 require 写的是 "acme/utils": "dev-main",那本地包的 composer.json 里 name 就必须是 "acme/utils",大小写、斜杠方向、短横线位置一个字符都不能错;version 字段可省略,但前提是本地包目录下有 Git 仓库且已 commit,否则 Composer 无法推断 dev-main 分支存在。
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
- 别用
"*"或"@dev"作为 require 版本——它们会绕过 path 仓库直连 Packagist - 如果本地包没初始化 Git,建议显式写
"version": "dev-main" - Windows 下路径含中文或空格可能触发解析失败,尽量避免
symlink 生效依赖本地包自己的 options 配置
很多人把 "options": {"symlink": true} 错加在主项目的 repositories 条目里,其实它必须写在**本地包自己的 composer.json 中**,否则 symlink 创建必然失败(尤其在 Windows 或 Docker 中)。
- Windows 用户必须以管理员身份运行终端,否则
mklink失败且无提示 - Docker 容器需加
--cap-add=SYS_ADMIN并确保挂载方式支持 symlink - 验证是否成功:Linux/macOS 执行
ls -la vendor/acme/utils,看到->;Windows 执行dir vendorcmeutils,看到
autoload 更新必须手动触发 dump-autoload
即使 symlink 已建好,改了本地包的 autoload 映射(比如新增 PSR-4 命名空间或调整 src/ 路径),vendor/autoload.php 也不会自动重生成映射表。
- 每次修改本地包的
autoload或autoload-dev后,必须在主项目根目录执行composer dump-autoload -o - 少一个反斜杠(如
"MyPackage\": "src/"写成"MyPackage": "src/")会导致命名空间完全不加载 - 测试类在
tests/下时,autoload-dev的映射末尾必须带反斜杠,否则use失败
本地包调试最隐蔽的问题,往往不是配置漏了哪一项,而是 symlink 创建失败后 Composer 静默 fallback 到 copy 模式——你改了代码,却还在看 vendor 里的旧副本。验证 symlink 是否真实存在,比反复检查 JSON 格式重要得多。










