require 命令不会自动识别本地 path 仓库，必须在项目根 composer.json 的 repositories 字段中正确配置相对路径、确保本地包含合法 composer.json、name 严格匹配、已 git init 并有 commit（或显式设 version），且 require 时必须指定 dev 版本如 dev-main。
直接说结论：require 命令本身不会自动识别本地 path 仓库，必须先配好 repositories、确保本地包合规，再用 composer require vendor/name:dev-main 显式指定开发版本，否则必报 “Could not find package”。
repositories 必须写在项目 composer.json 根级
Composer 只读取项目根目录下 composer.json 文件最外层的 repositories 字段，其他位置写的全无效。常见错误包括：
- 把
repositories塞进require、autoload或config里——完全不解析 - 在本地包自己的
composer.json里写repositories——对主项目毫无作用 -
url写成绝对路径（如C:/dev/my-pkg）或带file://前缀——应改用相对路径，例如"./packages/my-utils" -
url指向的是目录，不是composer.json文件本身；末尾不能加/（"./packages/my-utils/"会静默失效）
本地包目录必须满足三个硬性条件
就算 repositories 配对了，只要缺以下任一，Composer 就静默跳过，不报错也不提示：
- 目录下存在语法合法的
composer.json（无尾逗号、全双引号、JSON 格式正确） -
name字段值必须和你在主项目中require的**逐字一致**：大小写、短横线-、斜杠/全部敏感（"acme/utils"≠"Acme/utils"） - 该目录已运行
git init并至少有一个 commit；否则 Composer 拒绝识别分支名（如dev-main）；若暂未初始化 Git，可在本地包composer.json中显式加"version": "dev-main"临时绕过
require 时必须写明确的 dev 分支版本
path 类型仓库不走语义化版本解析，^1.0、*、省略版本号都会让 Composer 回退到 Packagist 查找，导致本地路径失效。正确写法只有：
-
composer require acme/utils:dev-main（前提是本地包composer.json有"version": "dev-main"或 Git 当前在main分支） -
composer require acme/utils:@dev（前提是项目已设"minimum-stability": "dev"） - 别写
composer require acme/utils（无版本），Composer 会按默认稳定性策略去“猜”，而本地包通常不满足stable要求，直接失败
装完后验证是否真链接成功
别只看 vendor/ 目录有没有文件，得确认底层链接和运行时加载是否生效：
- Linux/macOS 下运行
readlink vendor/acme/utils，输出应为你的本地路径（如../../packages/my-utils） - Windows 下运行
dir vendor\acme\utils，看到JUNCTION或 “快捷方式” 字样才算对 - 如果看到的是普通文件夹而非链接，说明 fallback 到了复制模式——这时要检查本地包自己的
composer.json是否含"options": {"symlink": true}，且 Windows 用户是否以管理员身份运行终端 - 类加载失败？运行
composer dump-autoload确保 autoload 映射写入vendor/composer/autoload_static.php
最关键的复杂点是：所有校验都静默进行，错一个字符、少一个引号、路径多一个斜杠，composer install 都不会报错，只会跳过你的本地包，转头去 Packagist 找——你得自己逐项核对 repositories 位置、url 路径、name 拼写、version 标识、Git 状态这五处，缺一不可。
