Composer本地包热更新需在本地包composer.json中显式配置"options": {"symlink": true},并满足路径相对、name逐字节一致、git已初始化且有commit等条件;否则默认复制模式,改代码不生效。

path仓库必须显式启用symlink才能热重载
Composer 默认对 path 仓库走复制(copy)模式,改本地包代码后必须 composer update 才生效——这根本不是热重载。真要改即生效,必须让 vendor 下的包目录变成符号链接,而触发 symlink 的唯一可靠方式,是在本地包自己的 composer.json 中写入 "options": {"symlink": true}。
常见错误包括:只在主项目 repositories 里加 "options"、或试图用 composer config --global 全局开启——这些全无效。symlink 开关只认本地包根目录下的 composer.json。
- Windows 用户需以管理员身份运行终端,否则
symlink创建失败且无提示 - Docker 场景下,容器启动时必须加
--cap-add=SYS_ADMIN,且挂载方式要支持符号链接 - macOS/Linux 上,若
ls -la vendor/acme/utils输出不含->,说明 fallback 到 copy 模式,立刻检查本地包是否漏了options段
require 必须用 @dev 或 dev-main,不能用 *
"acme/utils": "*" 看似宽松,实则危险:Composer 会优先查 Packagist,可能绕过你的本地 path 仓库,导致 composer update 后装的是远程旧版。
正确做法只有两种:
- 本地包
composer.json中设"version": "dev-main",主项目require写"acme/utils": "dev-main"—— 这样切分支后,composer update acme/utils才能触发 symlink 更新 - 更省心:统一用
"acme/utils": "@dev",它强制走 path 源,不查 Packagist,也不依赖本地包的version字段
别信“* 能自动匹配本地”,它只会增加静默失败概率。
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
路径、name、git 初始化三者缺一不可
哪怕 options 和 @dev 都对了,只要以下任一条件不满足,Composer 就静默跳过该仓库,composer install 报 Could not find package:
-
repositories中的url必须是相对路径,以./或../开头(如"../my-package"),不能是绝对路径、~、file://或末尾带/ - 本地包根目录下必须有合法
composer.json,其中name字段(如"acme/utils")必须与主项目require中的字符串逐字节一致(大小写、斜杠方向、连字符都不能错) - 本地包目录必须已执行
git init且至少有一个commit;否则 Composer 拒绝 symlink,直接 fallback 到 copy
验证路径是否被识别:运行 composer show --all | grep acme/utils,有输出才说明仓库已加载。
autoload 更新需手动触发,IDE 断点路径必须真实
symlink 生效 ≠ 类能被加载。即使 vendor 目录已软链成功,如果 autoload-dev 映射错了,phpunit 仍会报 Class not found。
-
autoload-dev的 PSR-4 映射末尾必须带反斜杠:"AcmeTests\": "tests/",少一个就断掉 - 无命名空间的辅助文件(如
tests/bootstrap.php)得用autoload-dev.files单独引入,不能塞进 PSR-4 - 改完
autoload-dev后,必须手动运行composer dump-autoload --dev,否则vendor/composer/autoload_dev.php不更新 - Xdebug 断点打不中?检查 IDE 中设置的源码路径是否和
readlink vendor/acme/utils返回的真实磁盘路径完全一致
最常被忽略的是 git 初始化和 autoload 映射末尾的反斜杠——这两个点不卡死,其他配置全对也白搭。

















