Invalid target path for symlink 错误源于路径校验失败，非权限问题：url须为绝对或项目内相对路径（禁用~/$HOME）、目标目录须真实存在且含有效composer.json、name字段须与require完全一致、symlinks:true须置于repositories的path条目内、本地包需声明"options":{"symlink":true}、须清除vendor和composer.lock后执行composer install --no-cache --prefer-source。
Invalid target path for symlink 错误不是权限问题
这个报错根本不是 Windows 管理员权限、Linux 文件系统只读或 Docker 权限不足导致的——它明确指向路径校验失败。Composer 在创建软链接前会严格检查 url 字段值，只要不满足格式要求，就直接拒绝，连尝试创建 symlink 的机会都没有。
常见错误现象：Invalid target path for symlink，但 ls -la ../my-pkg 明明能列出目录、composer.json 也存在、终端还是管理员身份运行。
-
url值含~或$HOME（如"url": "~/my-pkg"）→ 必须改为绝对路径（/home/user/my-pkg）或项目根目录相对路径（"../my-pkg"） - 目标路径本身是符号链接（例如
../my-pkg → /tmp/real-pkg）→ Composer 不解析嵌套软链，必须指向真实目录 - 目标目录为空，或只有
composer.json但语法错误（尾逗号、单引号、未闭合括号）→composer validate ../my-pkg/composer.json可验证 -
symlinks: true写在了config段而非repositories的具体 path 对象里 → 完全被忽略，必须写成：{"type": "path", "url": "../my-pkg", "symlinks": true}
name 字段大小写与分隔符必须逐字匹配
90% 的 Could not find package vendor/name 报错，根源是本地包 composer.json 中的 name 和主项目 require 里写的字符串不一致。Composer 不做任何 normalize，差一个字母、一个短横线、大小写错位，都算“不同包”。
例如主项目写了："acme/utils": "*"，那么本地包 composer.json 的 name 必须是 "acme/utils"，而不是："Acme/utils"、"acme_utils"、"acme-utils" 或 "acme/utils/"（末尾斜杠也不行）。
- 用
grep '"name":' ../my-pkg/composer.json直接提取值，和 require 字符串逐字符比对 - Windows 用户额外注意：路径中含中文、空格、括号时，某些 PHP 版本会静默截断路径，导致 name 校验跳过
- 通配符路径（如
"../packages/*"）下每个子目录都必须有独立composer.json，且各自name与 require 中对应项完全一致
symlink 生效需本地包自身声明 options
很多人以为只要主项目配置了 symlinks: true 就够了，其实关键一步在本地包自己的 composer.json 里——必须显式声明："options": {"symlink": true}。缺这句，Windows 下即使管理员运行也会 fallback 到复制；Docker 容器挂载宿主机目录时也常因此失效。
验证是否真用了软链：ls -la vendor/acme/utils（Linux/macOS）或 dir vendor\acme\utils（Windows），输出中要有 -> 或 <SYMLINKD> 才算成功。如果显示为普通文件夹，说明已 fallback。
- 本地包
composer.json中必须包含："options": {"symlink": true}（Composer 2.2+）或"options": {"symlink": true}（旧版兼容写法） - 改完本地包代码后，
composer install不会刷新链接，必须运行：composer update acme/utils - CI/CD 或上线环境严禁使用 path 仓库，
composer install --no-dev仍可能因repositories字段存在而报错，上线前务必移除该配置
vendor 和 composer.lock 残留会阻止 symlink 重建
即使所有配置和路径都正确，composer install 也不会主动把已存在的 vendor 子目录改成软链——它只按 composer.lock 还原状态。如果上次是 copy 安装，这次照样 copy。
必须手动清理才能触发重新解析和链接重建：
- 删除整个
vendor/目录：rm -rf vendor - 删除
composer.lock：rm composer.lock - 确保终端环境干净：VS Code 内置终端要彻底退出，不能只重启 pane；避免复用旧 shell 的 PATH 或 alias
- 执行：
composer install --no-cache --prefer-source（强制走 source 模式并尝试建链） - Windows 用户若仍失败，换用 PowerShell（以管理员身份）或确认已启用“开发者模式”
最容易被忽略的是：改了本地包代码却没运行 composer update vendor/name，只跑 composer install，结果 vendor 里还是旧副本——因为链接目标没变，只是源码变了而已。
