path仓库必须用相对路径且不能跨磁盘，如"../my-sdk"合法，而"C:/dev/my-sdk"或"/home/user/my-sdk"会静默失败；Windows需管理员权限启用symlink，require-dev中的本地包不被识别，核心依赖须置于require中。
path仓库必须用相对路径，且不能跨磁盘
Composer 的 path 类型仓库只接受相对于主项目 composer.json 文件的路径，比如 "../my-sdk" 合法，"C:/dev/my-sdk" 或 "/home/user/my-sdk" 会静默失败或报错 Repository not found。Windows 下尤其容易踩坑：即使你用的是 WSL 或 Docker，只要 Composer 进程运行在 Windows PHP 环境里，就仍受此限制。
实操建议：
- 把本地 SDK 目录放在主项目同级或子级（如
../sdk-core或./packages/sdk-core） - 路径中不要有空格或中文，否则某些旧版 Composer（
- 执行
composer install前，先用ls -la ../my-sdk/composer.json（Linux/macOS）或dir ..my-sdkcomposer.json（Windows）确认路径可达
本地包的 composer.json 必须含 name 和 autoload
如果本地 SDK 的 composer.json 缺少 name 字段，Composer 会跳过该仓库；若没配 autoload，即使安装成功，类也加载不了——这是最常被忽略的两个硬性条件。
正确示例（最小可用配置）：
{
"name": "acme/sdk-core",
"type": "library",
"autoload": {
"psr-4": {
"Acme\Sdk\": "src/"
}
}
}
注意点：
-
name必须与主项目require中声明的完全一致（包括大小写），例如主项目写"acme/sdk-core": "*"，本地包就不能叫"acme/sdkcore" -
autoload推荐用psr-4，别用files或classmap—— 后两者不支持命名空间自动映射，调试时会卡在Class not found - 本地包不需要
require主项目的任何依赖，它应保持独立可测试
符号链接行为取决于 Composer 版本和系统权限
Composer ≥ 2.0 默认为本地 path 包创建符号链接（symlink），但 Windows 非管理员 CMD/PowerShell 默认禁用符号链接，结果会 fallback 到硬链接或复制，导致修改本地包代码后主项目不生效。
验证方式：进入主项目 vendor/acme/sdk-core，执行 ls -l（Linux/macOS）或 dir（Windows），看到类似 acme/sdk-core -> ../my-sdk 才是正常 symlink。
解决办法：
- Windows：以管理员身份运行终端，再执行
composer install - macOS/Linux：确保
composer.json中没设"options": {"symlink": false} - 强制启用 symlink（所有平台）：
composer config --global use-symlinks true
require-dev 里的本地包不会被 path 仓库识别
如果你把本地 SDK 放在主项目的 require-dev 而不是 require 里，即使配置了 path 仓库，Composer 也不会把它链接进 vendor/。这会导致 composer install --no-dev 生产部署时直接缺失依赖，而开发时又一切正常——线上报错才暴露问题。
正确做法：
- 业务核心 SDK 必须放
require；仅用于测试工具、Mock 类的才放require-dev - 本地开发阶段，可通过
composer require acme/sdk-core:dev-main --dev临时加到require-dev，但上线前务必移回require - CI/CD 流水线中，用
composer install --no-dev验证是否遗漏了必需依赖
