Composer软链接由本地包的"options":{"symlink":true}控制，非主项目路径配置；path仓库url须为./或../开头的相对路径，且需确保包名、composer.json格式及Git初始化三者匹配。
Composer 的软链接（symlink）本身不靠“指定相对路径”来控制，而是由仓库类型、本地包配置和系统权限共同决定；你真正能配的，是 path 仓库的 url 字段——它必须是相对于主项目 composer.json 的路径，且不能带 ../ 开头以外的非法写法。
path 仓库的 url 必须用相对路径，但不是你想的那样
很多人以为 url 是“软链接目标路径”，其实它是 Composer 查找本地包源码的目录位置。这个路径只接受两种安全形式：
-
./packages/my-utils（推荐）：从项目根往下走，清晰、可移植、CI 友好 -
../my-utils（可用但需谨慎）：跨父目录，团队协作时容易因工作目录不同而失效
以下写法全部无效或危险：
-
~/my-utils或$HOME/my-utils：Composer 不解析环境变量 -
/absolute/path/to/my-utils：Linux/macOS 下可能静默失败，Windows 下完全不识别 -
../my-utils/（末尾带斜杠）：URL 解析失败，Composer 直接跳过该仓库 -
file:///path/to/my-utils：不是path类型的合法协议，会被忽略
软链接真正生效的开关在本地包里，不在主项目
即使 url 配对了，Composer 默认仍是复制（copy）模式。要让 vendor/vendor/name 变成指向本地目录的符号链接，关键在本地包自己的 composer.json：
- 必须加
"options": {"symlink": true}，写在根级（和name、autoload同层） - Windows 用户必须以管理员权限运行
composer update，否则创建 symlink 失败且无提示 - macOS/Linux 不需要特殊权限，但目标目录不能有同名文件阻碍链接创建
- 这个配置不会被主项目覆盖，也不会出现在
composer.lock中——它是本地包的“行为契约”
验证 symlink 是否真成功，别只看 vendor 目录存在
运行完 composer update vendor/name 后，仅检查 vendor/vendor/name 是否存在不够。要确认是否为真实软链接：
- Linux/macOS：
ls -la vendor/vendor/name—— 输出中应含-> ../my-utils字样 - Windows（CMD）：
dir vendor\vendor\name—— 应显示 - PHP 中
is_link('vendor/vendor/name')返回true才算到位 - 如果只是普通目录，说明
options.symlink没生效，或 Git 未初始化、或权限不足
为什么改了 path 仓库还报 “Could not find package”？
这不是路径问题，而是三处硬性匹配没对上：
- 主项目
require中的包名（如"acme/utils"）必须和本地包composer.json里的name字段逐字一致（大小写、短横线、斜杠全部敏感） - 本地包目录下必须有合法 JSON 格式的
composer.json，不能有尾逗号、单引号、中文引号 - 本地包必须已运行
git init && git add . && git commit -m "init"，否则dev-main分支无法被识别；若没 Git，可临时加"version": "dev-main"绕过
以上任一条件缺失，Composer 都会静默跳过该 path 仓库，回退到 Packagist 查找，最终报错“Could not find package”。它不提示“配置未生效”，只报“找不到包”——这是最常被误判的点。
