Composer path仓库需用相对于主项目composer.json的路径，如"../my-package"；require必须用dev-分支别名且匹配本地包version值，并设"minimum-stability":"dev"；启用软链接须配"options":{"symlink":true}或执行composer update包名。
path仓库配置必须写对相对路径
Composer 的 path 类型仓库只接受相对于主项目 composer.json 文件的路径，不能用 ~/、/absolute/path，也不能用 ../ 跨出项目根目录（Composer 2.4+ 会直接拒绝）。比如你的本地包在 ../my-package，主项目 composer.json 就得这么写：
"repositories": [
{
"type": "path",
"url": "../my-package"
}
]
常见错误：
-
url写成./packages/my-package，但实际目录是../../my-package→ 报Could not find package - 路径里多了一个空格或大小写不一致（如
My-Packagevsmy-package）→ name 匹配失败 - 目标目录下没有
composer.json，或里面缺"name"字段 → 解析失败，报Could not parse version constraint
require 必须用 dev- 分支别名，不是版本号
path 仓库不走语义化版本解析，所以 "my-vendor/my-package": "^1.0" 这类写法完全无效。必须用 dev- 开头的分支别名，例如 "dev-main" 或 "dev-develop"，且该分支名要和本地包 composer.json 中的 "version" 值严格一致。
同时顶层必须加这两行（否则 dev-main 会被过滤掉）：
"minimum-stability": "dev", "prefer-stable": true
容易踩的坑：
- 本地包
composer.json里写的是"version": "dev-main"，但主项目 require 写了"dev-master"→ 找不到匹配版本 - 忘了加
"minimum-stability": "dev"，报Could not find a matching version，而不是路径问题 - 写了
"@dev"（旧写法），但 Composer 2.2+ 已不推荐，建议统一用dev-main
软链接不会自动生效，必须手动 update
配置完 repositories 和 require 后，composer install 不会自动创建软链接——它默认做的是「复制」。要强制启用符号链接（Linux/macOS）或目录映射（Windows），有两个办法：
- 在
repositories里加"options": {"symlink": true}（Composer ≥2.2 支持） - 或者直接运行
composer update my-vendor/my-package（推荐，精准、可控）
注意：
- 不要删
vendor/和composer.lock后再install—— 这会让本地包被完整复制进去，失去“改即生效”的意义 - 改了本地包代码后，vendor 目录里的文件时间戳不会变，必须重新
update才能刷新链接 - 验证是否真成了软链接：
readlink vendor/my-vendor/my-package（Unix）或dir vendor\my-vendor\my-package（Windows）
composer link 命令只适用于已安装包，慎用
composer link 不是通用方案，它只对「已经通过 composer require 安装过的包」起作用，本质是在 vendor/ 下建软链接，绕过版本约束。但它不更新 composer.lock，也不同步 autoload，后续 composer update 极可能把它覆盖回复制模式。
使用前提：
- 先确保包已安装：
composer require my-vendor/my-package - 进入本地包目录，执行
composer link（需 Composer ≥2.4 或装了composer-plugin-link） - 回到主项目，执行
composer link my-vendor/my-package
真实场景中，90% 的调试失败都源于误用了 link 而没走 path + update 流程。它适合临时验证，不适合长期开发。
最易忽略的一点：Windows 下即使启用了 symlink，某些 IDE 或 PHP 运行时仍可能 fallback 到复制行为，务必用 readlink 或 dir 确认实际类型，别只看文件内容是否更新。
