本地包必须用dev-main（或对应分支名）才能被识别，name字段须与require完全一致，repositories需在主项目composer.json中配置path源，且目录必须为含有效composer.json的Git仓库。
本地包必须用 dev-main（或 dev-master）才能被识别，写 1.0.0、main、@dev 都会失败。
path 仓库的 composer.json 必须有合法 name 字段
本地包目录下的 composer.json 里 name 值，要和主项目 require 中写的完全一致，包括 vendor 段。比如本地包写了 "name": "acme/utils"，主项目就得写 "acme/utils": "dev-main"。
常见错误：
-
"Acme/utils"（大小写错）→ Composer 不认 -
"acme-utils"（用了短横线）→ 和 name 不匹配 -
"utils"（缺 vendor 段）→ 直接报Could not find package
require 版本号只能写 dev- 开头的分支名
path 类型仓库不看本地包 composer.json 里的 version 字段，只按当前 Git 分支或 HEAD 解析。所以你写 "version": "1.2.3" 没用，必须在主项目中用 "dev-main" 这类形式 require。
注意点：
- 分支名必须存在，且本地目录是 Git 仓库（哪怕没 push）
- 如果默认分支叫
develop，就得写"dev-develop"，不是"dev-main" - 不用打 tag，也不需要
minimum-stability设为dev—— path 源天然绕过稳定性检查
repositories 配置必须写在主项目根 composer.json 里
不能写在本地包自己的 composer.json 中，也不能靠全局配置。正确写法是：
{
"repositories": [
{
"type": "path",
"url": "../my-local-package"
}
],
"require": {
"acme/utils": "dev-main"
}
}
关键细节：
-
url支持相对路径（推荐）或绝对路径，但不能含~或环境变量 - 路径必须可读，且指向一个含有效
composer.json的目录 - 多个本地包就加多个
path条目，顺序无关
运行 install/update 后实际链接的是符号链接
Composer 对 path 仓库的处理是创建 symlink，不是复制文件。这意味着你在本地包里改代码，主项目立刻可见，无需重新 install。
但要注意：
- Windows 下若未启用开发者模式，symlink 可能失败，报错
failed to create symbolic link - 某些 CI 环境禁止 symlink，此时需改用
vcs类型 + SSH key 认证 - 如果本地包目录被移动或删除，下次
composer install会直接报错，不会自动降级到 Packagist
最容易被忽略的一点：dev-main 是分支名，不是版本别名；它背后绑定的是当前 HEAD 的 commit hash，一旦你在本地包里 git commit，主项目下次 update 就会拉新代码——这既是热更新的优势，也是意外行为的来源。
