用 repositories + path 是最可靠可复现的本地调试方式，因它通过配置本地路径仓库并设 symlink 选项，使 composer update vendor/name 创建软链接指向本地代码，绕过 composer.lock 的远程版本锁定；而 composer link 仅适用于已安装包的临时验证，易被后续 update 覆盖。

用 repositories + path 类型是最可靠、可复现的本地调试方式，composer link 仅适合已安装包的临时验证，且极易被后续 composer update 覆盖。

为什么 composer install 不加载你改的本地代码？

Composer 默认只认 composer.lock 里锁定的远程包版本，完全忽略你本地目录下的任何修改。即使你把源码 clone 到项目旁边，只要 require 写的是 "vendor/name": "^2.1"，它就去 Packagist 下载压缩包，不会看一眼你硬盘上的文件。

常见错误现象：

• Could not find package vendor/name —— 八成是 name 字段不逐字匹配，或 url 指向了空目录/文件而非含 composer.json 的目录
• 执行 composer update 后，vendor/vendor/name 还是普通目录，不是符号链接 —— "options": {"symlink": true} 没配，或 Windows 下没用管理员权限运行终端
• composer install 完全没反应，也不报错 —— repositories 被写进了 config 或 extra 里，而不是和 require 平级

配置 path 仓库必须满足的硬性条件

漏一条，composer update 就静默跳过，连 warning 都不给。

Academic Composer Upload

辅助学术写作，包括查找资料、生成大纲、引用扩写及润色风格，同时确保引用规范。

下载

• repositories 必须写在主项目 composer.json 根层级，和 require 同级，不能嵌套
• url 必须是相对路径（如 "../my-package"），不能带 file://、不能以 / 结尾、不能用 ~ 或绝对路径
• 本地包目录下必须有合法 composer.json，且其中 name 字段必须与主项目 require 中的包名**逐字节一致**（大小写、分隔符、vendor 名全敏感）
• 必须显式启用 symlink："options": {"symlink": true} 要加在 repositories 条目里，不是全局 config
• 本地包目录需已初始化 Git（否则 Composer 可能无法推断 dev-main 分支；若无 Git，建议在本地包 composer.json 中加 "version": "dev-main"）

执行流程与关键命令

不要用 composer install 引入新本地包——它只还原 lock，不读取新 repositories 配置。

• 先编辑主项目 composer.json，加入 repositories 块和对应 require（版本写 "dev-main" 或 "*"）
• 运行 composer update vendor/name（必须带包名！否则可能误更新其他依赖）
• 验证是否成功：ls -la vendor/vendor/name（Linux/macOS）或 dir vendor\vendor\name（Windows），看到 -> 符号即为软链接生效
• 改本地包代码后，主项目立刻可见效果，无需任何额外命令

composer link 的真实适用边界

它不是“替代方案”，而是“补丁工具”：只对已通过 Composer 正常安装过的包有效，本质是在 vendor/ 下重建软链接。

• 前提：包必须已存在 vendor/ 中（即先 composer require vendor/name）
• 操作顺序：进本地包目录 → composer link → 回主项目 → composer link vendor/name
• 风险点：不改 composer.lock，不触发 autoload 重生成；下次 composer update 会直接覆盖掉这个链接，变回普通目录
• 不推荐用于协作开发或 CI 流程，因为行为不可复现

真正容易被忽略的是：无论用哪种方式，本地包自身的 autoload（尤其是 PSR-4 映射）必须正确，否则类找不到——这和主项目无关，是本地包自己的事。