如何在Composer中引用本地文件夹作为依赖？（模块化开发）

composer需显式声明path仓库类型，url为相对路径，name须与本地包composer.json完全一致，且必须含autoload；默认symlink失败时会静默复制，可加”options”:{“symlink”:true}强制链接。

用 path 仓库类型直接链接本地目录

Composer 不支持直接写 "vendor/package": "path/to/local" 这种写法，必须显式声明一个 path 类型仓库。否则会报错 "Could not find a matching version of package vendor/package" 或跳过本地路径。

在项目根目录的 composer.json 中添加：

{   "repositories": [     {       "type": "path",       "url": "./packages/my-package"     }   ],   "require": {     "my-vendor/my-package": "*"   } }

注意： url 是相对于 composer.json 的路径，不是绝对路径；my-vendor/my-package 必须与目标包 composer.json 里的 "name" 完全一致。

• 目标包（即本地文件夹）必须有合法的 composer.json，且含 "name" 和 "autoload"
• 如果目标包没有 version 字段，"*" 会匹配到 dev-main（或 dev-master），不是 v1.0.0
• 执行 composer install 或 composer update my-vendor/my-package 才会真正软链接（symlink）过去

为什么 composer update 没反应？检查软链接和缓存

常见现象：改了本地包代码，但项目里运行时没生效——大概率是 Composer 并没真正链接，而是复制了一份进 vendor/。

根本原因：默认情况下，path 仓库启用 "symlink": true（Composer 2.2+），但若目标目录不可 symlink（如 windows 非管理员、某些 docker 环境），它会 fallback 到 copy 模式，且不会提示。

• 运行 composer show my-vendor/my-package，看输出里 source 是 path 还是 dist
• 检查 vendor/my-vendor/my-package 是否是符号链接：ls -la vendor/my-vendor/my-package
• 强制启用 symlink：在 repositories 条目里加 "options": {"symlink": true}
• 清缓存再重装：composer clear-cache && composer update my-vendor/my-package --no-cache

开发时频繁修改依赖，怎么避免每次 composer update？

手动跑命令太慢，尤其在 CI 或多包协作时。关键是让 Composer “感知”到本地变更，而不是靠重装。

• 确保本地包 composer.json 里 "autoload" 配置正确，否则即使链接成功，autoload.php 也加载不到新类
• 改完本地包后，只需在主项目中执行 composer dump-autoload（不加 --optimize），刷新自动加载映射
• 如果用了 PSR-4，且本地包源码结构和命名空间严格对应，连 dump-autoload 都不一定需要——PHP 会按路径实时解析
• 别在本地包里改 composer.json 的 "version"，这会触发 Composer 认为“版本变了”，反而断开 symlink

Windows 下 symlink 失败或权限报错怎么办？

错误信息通常是 "failed to create symbolic link: A required privilege is not held by the client"，或者 vendor/ 里生成的是副本而非链接。

• 以管理员身份运行终端（CMD/PowerShell/git bash），再执行 composer update
• 或关闭 symlink：在 repositories 中设 "options": {"symlink": false}，但之后必须手动 composer dump-autoload 且无法热更新
• Docker for Windows 用户：确保共享文件夹启用了 cached 或 delegated 选项，否则 symlink 在容器内不可见
• 更稳的替代方案：用 composer config repositories.local path ./packages/my-package 命令动态注册，避免手写 JSON 出错

最常被忽略的一点：本地包的 composer.json 里不能漏掉 "autoload" ——哪怕只是空对象 {"autoload": {}}，否则 Composer 会拒绝识别该包为有效依赖。