本地包composer.json必须包含name（格式vendor/name）和version（如dev-main）字段，缺一则composer静默跳过；url须为目录路径而非文件路径；options需在主项目repositories中配置，控制symlink行为。
path仓库的composer.json必须包含哪些字段
本地包目录下的composer.json不是可选配置，而是硬性准入门槛。Composer 读取 path 仓库时，只认两个字段：必须有name，且必须合法（格式为vendor/name，不能含空格或非法字符）；必须有version，哪怕只是"dev-main"或"1.0.x-dev"。
常见错误现象：Could not find a matching version of package vendor/name——大概率是本地composer.json里漏了name，或者version为空、写成了"null"或""。
-
name必须和你在主项目require中写的完全一致（大小写敏感、连字符位置都不能错） -
version不参与语义化版本比对，但缺失会导致 Composer 直接跳过该目录，不报错也不提示 - 如果本地包是 Git 仓库，
version字段会被忽略，实际用的是当前分支名（如main→dev-main），但字段仍需存在 -
autoload不是必需字段，但没配就无法自动加载类——主项目composer dump-autoload不会扫描vendor/下的 symlink 目录，只认它自己的映射
为什么url不能指向composer.json文件本身
url值必须是一个**目录路径**，比如"./packages/my-utils"，而不是"./packages/my-utils/composer.json"。Composer 启动后会进入该目录，再尝试读取里面的composer.json。如果指向文件，就会报Directory not found或静默失败。
相对路径推荐用./开头，避免因执行位置不同导致解析错乱；绝对路径虽可用（如/home/user/pkg），但在 CI 或换机器时极易失效。
- Windows 下路径分隔符用
/或\都行，但file://前缀一律不支持 - 通配符如
"../packages/*"是合法的，但每个匹配子目录都必须含独立的composer.json，缺一个就跳过整个通配结果 - 路径中不能含
~或环境变量（如$HOME），Composer 不做展开
options配置symlink行为的实操要点
默认情况下，Composer 对 path 包使用符号链接（Linux/macOS）或复制（Windows），但你可以用options显式控制。这个配置必须写在repositories条目里，不是本地包的composer.json中。
示例配置：
{
"type": "path",
"url": "./packages/my-utils",
"options": {
"symlink": false
}
}
这样会强制复制而非链接，适合 CI 环境或 Windows 开发者未启用开发者模式的情况。
-
"symlink": true在 Linux/macOS 是默认行为，显式写上更清晰，也兼容老版本 Composer（ -
"symlink": false等价于设"preferred-install": {"vendor/name": "dist"}，但前者粒度更细 - Windows 下若未启用开发者模式或未以管理员身份运行终端，
symlink: true会静默退化为复制，不报错 - CI/CD 流水线中必须禁用 symlink（即设
false），否则构建必然失败——因为路径在构建机上不存在
本地改了代码，为什么composer install不生效
composer install只重建缺失的链接，不会刷新已有 symlink 的目标路径。它完全依赖composer.lock里记录的解析结果，而这个结果是在上次composer update或composer require时固化下来的。
也就是说：你改完本地包的 PHP 代码，composer install什么也不会做；必须运行composer update vendor/name，才会重新解析 path、校验name、重建 symlink。
- 不要用
composer update无参数调用——它会重算全部依赖，可能意外升级其他包 - 如果本地包改了
composer.json里的name或version，也要update vendor/name，否则 lock 文件不更新 -
composer dump-autoload和 symlink 完全无关，它只刷新类自动加载映射，不影响链接状态 - 验证是否真链接成功：Linux/macOS 下运行
ls -la vendor/vendor/name，输出应含->；Windows 下用dir vendor endor ame，看是否标有<symlinkd></symlinkd>
