路径仓库配置必须写在根composer.json的repositories字段中，且为索引数组，每项形如{"type":"path","url":"packages/my-sdk"}，url须为相对路径，改后需clear-cache，require版本必须用*@dev等本地标识，否则Composer将忽略本地包而访问Packagist。

path仓库配置必须写在根composer.json里，否则子包根本不会被识别

这里有个常见的误解：很多人以为只要子目录下有个规范的composer.json文件，Composer就能自动识别。其实不然。Composer的“视野”只聚焦于项目根目录下的那个composer.json，它不会主动去扫描子目录。换句话说，如果你没在根配置的repositories字段里明确声明，那么子包配置得再完美，对Composer来说也等于不存在。

典型的错误场景就是：你在packages/my-sdk/composer.json里正确定义了"name": "acme/my-sdk"，但回到根项目执行composer require acme/my-sdk时，却收到一个冷冰冰的could not find package acme/my-sdk。问题根源就在于，你还没告诉Composer该去哪里找这个包。

• 关键在于，repositories必须是一个索引数组。每一项都应该是一个独立的对象，形如{"type":"path","url":"packages/my-sdk"}。千万别写成键值对的对象形式，那会导致配置被忽略。
• url路径必须是相对于根composer.json的。记住，不要以./开头，也绝对不要使用绝对路径——后者是团队协作时的“杀手”，换台机器配置就失效了。
• 路径匹配不支持通配符递归。也就是说，如果你的包在packages/core/v2，只写一个"packages/*"是找不到它的，必须为v2这个子目录单独添加一条声明。
• 修改完repositories配置后，一个好习惯是立刻运行composer clear-cache。Composer有缓存机制，不清除缓存的话，新加的路径可能不会立即生效。

require里的版本必须用*@dev，别写^1.0或dev-main

这是另一个高频踩坑点。对于path类型的本地包，Composer不会对其进行语义化版本解析。如果你在根项目的require里写了"acme/my-sdk": "^1.0"，会发生什么？Composer会直接跳过你本地的packages/my-sdk目录，转而跑到Packagist上去寻找已发布的1.x版本。结果就是你本地修改的代码完全不会被加载，调试起来会让人一头雾水。

正确的写法其实很明确，主要有三种："*@dev"、"@dev"、或者"dev-main"（使用后者需要确保子包的分支名确实是main）。它们的核心作用是一致的：告诉Composer“无条件使用本地目录的最新代码”，彻底绕过远程仓库的版本匹配逻辑。

• 子包自身的composer.json里，version字段甚至可以省略，因为Composer在解析path包时根本不读取它。真正起标识作用的是name字段和路径的一致性。
• 当多个子包存在互相依赖时，务必注意：被依赖的包也必须在根的repositories里声明。否则，Composer在解析复杂的依赖树时会卡住，提示找不到包。
• 在CI/CD等自动化环境中，有时会禁用符号链接。别担心，即便在禁用了symlink的Windows容器里，使用@dev标识依然能工作，只是Composer会退而求其次，采用复制文件的方式替代创建链接。

vendor里不是复制而是符号链接？那得确认symlink选项和系统支持

理想情况下，vendor/acme/my-sdk应该是一个指向packages/my-sdk的软链接（符号链接）。这样，你在子包里修改代码，主项目就能即时生效。但如果你发现vendor目录下是完整的文件复制，那就说明符号链接创建失败了。

导致失败的原因可能有好几种：在Windows上，可能终端没有以管理员身份运行，或者系统未开启“开发者模式”；在Linux或macOS上，可能是文件系统挂载时设置了noexec或nosymfollow参数；当然，也可能是使用的Composer版本过于老旧，没有默认启用符号链接功能。

• 最稳妥的解决方案，是在repositories的配置条目里显式地加上"options": {"symlink": true}。这相当于给Composer一个明确的指令。
• 在执行composer install之前，最好确保vendor/目录是空的。残留的旧复制文件可能会干扰新链接的创建。
• 如何验证链接是否成功？在命令行中运行ls -la vendor/acme/my-sdk（Windows可用dir命令查看属性），如果输出结果中包含类似-> ../../packages/my-sdk的箭头指示，才算真正建立了链接。
• 需要警惕的是，当链接创建失败时，Composer会自动回退到复制（copy）模式，而且这个过程通常是静默的，不会抛出错误。因此，主动检查链接状态是一个好习惯。

改了子包代码，vendor里还是旧的？别信dump-autoload

composer dump-autoload这个命令被误解得太深了。它只做一件事：刷新PSR-4或PSR-0的类自动加载映射表（即更新vendor/composer/autoload_*.php这些文件）。它完全不会去同步或更新vendor目录下具体包的文件内容。所以，你修改了packages/my-sdk/src/Client.php之后，运行dump-autoload，vendor/acme/my-sdk/src/Client.php里的内容依然是旧的，这一点也不奇怪。

真正能触发本地包代码同步的命令是composer update。而且，为了保险起见，最好加上--with-dependencies参数，否则Composer可能会认为已安装的path包无需更新而跳过它。

• 推荐的命令是：composer update acme/my-sdk --with-dependencies。这能确保目标包及其依赖都被更新。
• 有时候，你明明改了子包的源代码，但没动composer.json，Composer可能会判断“版本无变化”而拒绝更新。这时可以尝试加上--force参数强制重新拉取（Composer 2.2及以上版本支持）。
• 还有一个更彻底但往往有效的方法：直接删除vendor下的对应目录，然后重新更新。例如：rm -rf vendor/acme/my-sdk && composer update acme/my-sdk。
• 另一个衍生问题：为什么子包tests/目录下的测试类，在根项目运行phpunit时找不到？这是因为autoload-dev配置默认不会从path包中继承。解决方法是在根项目的composer.json的autoload-dev部分，手动添加子包测试目录的路径。

说到底，路径拼写、包名大小写、符号链接权限、缓存残留……这些问题单独看都不复杂，但组合在一起，就成了Monorepo项目中最容易让人卡住的暗礁。尤其是在跨操作系统协作的团队里，同一个配置，在开发者的Mac上创建了完美的软链接，到了另一位同事的Windows电脑上却变成了文件复制，这种环境差异导致的问题往往隐藏得更深，排查起来也更费周折。