本地开发时composer.json的name字段必须为vendor/name格式，如"acme/my-utils"；require需显式指定dev-分支名；repositories须配置在主项目根composer.json顶层，且启用symlink才能实时同步代码。
本地开发时 composer.json 的 name 字段必须带 vendor/name 格式
本地包的 composer.json 里 name 写成 "my-utils" 或 "utils"，composer require 就一定失败——Composer 不认这种裸名。它只匹配完整命名空间，且严格区分大小写和斜杠方向。
正确写法示例：
{
"name": "acme/my-utils",
"type": "library",
"autoload": {
"psr-4": { "Acme\Utils\": "src/" }
}
}
-
name必须含一个/，前半段是 vendor 名（小写字母、数字、短横线），后半段是包名 - 若主项目
require写的是"acme/my-utils": "dev-main"，本地包name却是"Acme/my-utils"（首字母大写）或"acme_my-utils"（下划线），就直接跳过该目录 - 不建议用中文、空格、点号（.）或大写字母开头
version 字段不是必须的，但 require 时必须用 dev-分支名
path 类型仓库下，Composer 基本忽略 version 字段值，而是靠 Git 分支名识别版本。如果你本地包在 main 分支，但 require 写 "^1.0" 或 "*"，就会报 Could not find a matching version。
- 本地包
composer.json中可写"version": "dev-main"，也可不写；但主项目require必须显式指定"dev-main"、"dev-develop"等实际存在的分支名 - 分支名必须真实存在：执行过
git init且至少有 1 次 commit，否则 Composer 扫描时会静默跳过整个目录 - Windows 下若未启用开发者模式或未以管理员权限运行命令行，
dev-main可能被识别为无效分支（尤其搭配 symlink 时）
主项目 repositories 配置必须写在根 composer.json 里
把 repositories 塞进本地包自己的 composer.json，或者误放在 config、extra、require 字段下，Composer 完全不会读取——它只看主项目根目录下 composer.json 的顶层 repositories 数组。
- 必须是 JSON 数组格式，哪怕只有一个源也要写成
[{ "type": "path", "url": "./packages/my-utils" }] -
url推荐用相对路径（如"./packages/my-utils"），禁用file://、~/、$HOME等写法；Windows 下统一用/作分隔符更稳妥 - 配置完别忘了验证是否加载成功：运行
composer config --list | grep repositories，能看到你配的路径才算生效
启用 symlink 才能实时同步代码修改
默认情况下，Composer 对 path 仓库使用 copy 模式，改完本地包代码，主项目里完全感知不到——除非你手动 composer update vendor/name 并且已启用 symlink。
- 在
repositories条目中加"options": {"symlink": true}，Linux/macOS 通常自动生效；Windows 必须显式写且确保系统支持（开启“开发者模式”或以管理员身份运行命令行） - 验证是否成功：Linux/macOS 运行
ls -la vendor/acme/my-utils，应看到->指向源目录；Windows 运行dir vendorcmemy-utils，类型应为“快捷方式” - CI 环境等不支持 symlink 的场景，可设
"preferred-install": {"acme/my-utils": "dist"}强制复制
真正卡住人的从来不是语法，而是三处对齐没做全：主项目 repositories 配置位置、本地包 name 和 require 中的名称、Git 分支名与 dev-xxx 的一致性——漏掉任意一个，Composer 就当它不存在。
