Composer本地包软链接怎么用？完整操作流程-composer-PHP中文网

Composer path仓库需用相对于主项目composer.json的路径，如"../my-package"；require必须用dev-分支别名且匹配本地包version值，并设"minimum-stability":"dev"；启用软链接须配"options":{"symlink":true}或执行composer update包名。

composer本地包软链接怎么用？完整操作流程

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-Package vs my-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），有两个办法：

Academic Composer Upload

辅助学术写作，包括查找资料、生成大纲、引用扩写及润色风格，同时确保引用规范。

下载

在 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 极可能把它覆盖回复制模式。

使用前提：