本地包 require 失败主因是 repositories 配置位置错误或 name/url 不匹配：必须置于根 composer.json 顶层，首位禁用 packagist.org，path 类型 url 须为相对路径且指向含合法 composer.json 的目录，require 必须带 dev-main 等开发版标识，并在本地包中声明 "options": {"symlink": true}。
本地包用 composer require 报 Could not find package，基本不是网络或缓存问题，而是 Composer 根本没去读你写的那个目录——90% 的 case 都卡在 name 字段不匹配、url 指向错误，或 repositories 配置压根没被加载。
repositories 必须写在项目根 composer.json 的顶层
Composer 只读取项目根目录下 composer.json 文件最外层的 repositories 字段。写在子目录、嵌套在 require 或 config 里，全部无效。
- 错误位置：
"require": { ... }, "extra": { "repositories": [...] }→ 被忽略 - 正确结构：和
require、autoload同级，直接在 JSON 根层级 - 必须加
{"packagist.org": false}在repositories数组首位，否则你的本地源永远排第二，不会生效 - 删掉
vendor/和composer.lock，再跑composer install --verbose，看日志里有没有Reading ../my-pkg/composer.json
path 类型仓库的 url 必须是相对路径且指向含 composer.json 的目录
type: "path" 是唯一支持本地文件系统路径的类型，但它对路径写法极其敏感。
-
url必须以./或../开头，例如"./packages/my-utils"✅；"my-utils"或"/home/user/my-utils"❌（静默失败） -
url必须指向**含合法composer.json的目录**，不能是父级目录，也不能带尾部斜杠："../my-pkg/"会被忽略 - 该目录下的
composer.json必须语法正确，且name字段值要和require中写的字符串**逐字一致**（大小写、短横线、斜杠全部敏感） - Windows 下若用绝对路径，必须带盘符（如
C:/dev/my-pkg），但强烈推荐统一用相对路径避免跨平台问题
require 时必须显式指定开发版标识，不能省略或写死语义版本
path 类型仓库不参与语义化版本解析，它只认明确的开发分支别名或 version 字段值。
- 别写
composer require vendor/name:1.2.3→ 会被当远程包查，报Could not find package - 别写
composer require vendor/name（无版本）→ Composer 按默认稳定性策略“猜”，通常失败 - 正确写法：
composer require vendor/name:dev-main，前提是本地包在main分支，或其composer.json中有"version": "dev-main" - 如果本地包还没初始化 Git，可临时加
"version": "dev-main"绕过分支检查
验证是否真生效：看符号链接，不是看 vendor 目录有没有文件夹
path 仓库的本质是软链接，不是拷贝。光看 vendor/ 下有没有文件夹毫无意义。
- Linux/macOS：运行
ls -la vendor/vendor/name，输出含->指向你本地路径才算成功 - Windows：运行
dir vendor\vendor\name，看到JUNCTION或真实路径指向才对 - 执行
composer show vendor/name，若显示source : path /your/local/path，说明识别成功 - 检查
composer.lock中该包的source.type是否为path，source.url是否是你写的相对路径（注意 lock 文件里会转成绝对路径）
最容易被忽略的一点：本地包自己的 composer.json 里必须声明 "options": {"symlink": true}，否则即使配置全对，Windows 或 Docker 环境也会 fallback 到复制模式，改代码完全不生效。
