必须在项目根目录composer.json的repositories数组中配置type为"path"、url为相对路径（如"../my-package"）、且本地包composer.json的name与require完全一致，否则静默失效。

Composer 的 path 仓库类型怎么配才生效

本地包路径映射不生效，大概率是 path 仓库配置没写对位置，或路径没按 Composer 要求规范写。它必须定义在项目根目录的 composer.json 里，且是顶层 repositories 数组项，不能嵌套在其他字段下。

关键点：

• type 必须为 "path"（字符串，不是 path 或 local）
• url 是本地绝对路径或相对于当前 composer.json 的相对路径，推荐用相对路径（如 ../my-package），避免换机器失效
• 该路径下必须存在合法的 composer.json，且其中 name 字段要和你 require 的包名完全一致（包括 vendor 名）
• 如果路径含空格或特殊字符，确保 shell 层面能正确解析——但更稳妥的做法是避开空格

为什么 composer install 没拉本地包，还是走 Packagist

Composer 默认优先使用已缓存的 dist 包或远程源，即使你加了 path 仓库，也不会自动切换，除非明确要求“强制走本地”。常见原因有：

Academic Composer Upload

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

下载

• 没执行 composer update vendor/name，只跑 install —— install 不重新解析仓库策略，只按 composer.lock 安装
• composer.lock 里该包仍指向 Packagist 的 dist URL，需先删 lock 文件或运行 composer update vendor/name --with-dependencies
• 包名拼写不一致：比如本地 composer.json 写的是 "name": "acme/utils"，但 require 写成 "acme/utils-dev"，匹配失败就回退远程
• 本地包的 version 字段值是 dev-main 这类非稳定版本，而 minimum-stability 设为 stable，导致被跳过

调试时怎么确认 Composer 真的加载了本地代码

光看 composer show vendor/name 输出不够，它可能显示本地路径但实际加载的仍是 vendor 里的旧副本。最直接验证方式是改本地包代码并观察运行时行为变化：

• 在本地包的某个函数里加一行 echo "LOCAL HIT "; die;，然后运行项目入口脚本，看到输出才算真正命中
• 检查 vendor/vendor/name 目录是否为符号链接（Linux/macOS）或 junction（Windows）——Composer 2.2+ 默认创建软链；若看到一堆真实文件，说明没走 path 映射
• 运行 composer diagnose，它会提示是否有仓库配置冲突或路径不可读
• 加 -v 参数重跑 update，看日志里是否出现 Found package vendor/name at path ../my-package

路径映射后 IDE 跳转和自动补全为啥还找不到符号

PHPStorm、VS Code 等工具依赖 vendor 目录结构做索引，而 path 映射生成的是软链，部分编辑器默认不跟随符号链接解析，或缓存了旧的 vendor 结构。

• PHPStorm：右键点击 vendor/vendor/name → Reload project，或清空 File > Invalidate Caches and Restart
• VS Code + Intelephense：关闭再打开工作区，或手动触发 Intelephense: Index workspace
• 确保本地包的 composer.json 里 autoload 配置正确（如 "psr-4": {"Acme\": "src/"}），否则即使路径对了，IDE 也识别不了命名空间
• 如果本地包用了 path 但又依赖另一个本地包，别嵌套多层 path —— Composer 不递归解析子依赖的仓库配置，子依赖得单独在主项目里声明

路径映射看着简单，但 Composer 对路径合法性、版本稳定性、锁文件状态、IDE 索引机制这几处的耦合非常敏感，任意一环断掉都会静默回退到远程包，调试时得逐层确认，而不是只盯一个配置项。