path类型仓库是唯一真正零带宽、可实时联动的方案，因其跳过所有网络请求、仅验证本地目录与composer.json合法性，并严格比对name和version字段；其他方式均存在隐性开销或配置失效风险。
Composer 管理本地包，path 类型仓库是唯一真正零带宽、可实时联动的方案；所谓“中文镜像”只是缓存加速手段，对本地开发无实质帮助，反而可能掩盖 path 配置错误。
为什么path是唯一靠谱的本地包方案
path 仓库跳过所有网络请求：不查 Packagist、不下载 ZIP、不走 Git clone，只验证本地目录是否存在、composer.json 是否合法、name 和 version 是否匹配。其他方式都有隐性开销：
-
artifact：强制解压 ZIP 并校验哈希，仍依赖文件系统操作 -
package+file://：触发元数据归一化，部分场景 fallback 到远程源 - 直接在
require里写路径（如"vendor/name": "./local"）：语法错误，Composer 直接退出
repositories 配置必须满足的硬性条件
Composer 只有先识别出“这是个包源”，后续 require 才能命中。常见静默失效，往往卡在这几步：
-
repositories必须是项目根composer.json的顶层字段，不能嵌套在config或extra里 -
url值必须是双引号包裹的字符串，支持相对路径（如"../my-package"）或绝对路径（如"/Users/me/my-package"），不能含file://、~或环境变量 - 路径指向的必须是**目录**，且该目录下存在合法
composer.json（无语法错误、无尾逗号、全用双引号） - Windows 下路径分隔符必须用
/或\，单反斜杠会导致 JSON 解析失败
name 和 version 必须严格逐字符匹配
path 仓库不做语义化版本解析，只做字符串比对。错一个字符就报 Could not find package：
- 本地包
composer.json中"name": "myorg/chinese-utils"，你就得在主项目require里写"myorg/chinese-utils"—— 大小写、斜杠方向、vendor 名全部一致 - 若本地包
version是"dev-main"，require就得写"dev-main"或"*@dev"；写"^1.0"或"*"在默认minimum-stability: stable下会被跳过 - 没写
version字段时，Composer 依赖 Git 分支名推断：分支main→dev-main，develop→dev-develop；此时require必须显式匹配
为什么 vendor 里是复制而不是符号链接
Composer 默认行为就是复制。所谓“软链接”必须显式启用，且只对 path 类型仓库生效：
- 最稳妥方式：在**本地包自己的
composer.json** 中加"options": {"symlink": true}（不是主项目的配置） - Windows 下需管理员权限运行终端，否则
mklink失败，Composer 静默 fallback 成硬拷贝 -
composer install不触发 symlink 创建；必须执行composer update vendor/name或全量composer update - 验证是否成功：
ls -la vendor/vendor/name（macOS/Linux）输出中应含->指向你本地源码路径
CI/CD 环境里 path 几乎必然失败——因为路径不存在，而且一旦误提交到 Git，协作成员 composer install 就会卡住。生产部署前务必删掉 repositories 中的 path 条目，改用私有 Packagist 或 Git tag 版本。
