Composer中使用path仓库配置本地包的完整指南-composer-PHP中文网

composer 的 path 仓库通过符号链接加载本地包，需在根 composer.json 的 repositories 数组中配置路径、name 和 version 三者严格对齐，并执行 composer update 触发链接重建。

composer中使用path仓库配置本地包的完整指南

Composer 用 path 仓库加载本地包，不是“复制安装”，而是按需建立符号链接——前提是路径、name、version 三者对齐，且你执行的是 composer update 而非 composer install。

path 仓库配置必须写在项目根 composer.json 的 repositories 数组里

它不会从子目录、vendor 或任意位置自动扫描。写错位置（比如塞进 require 或 config 字段）等于没写。

repositories 是一个数组，哪怕只配一个 path 源，也要写成 [{ "type": "path", "url": "./packages/my-lib" }]
url 必须是相对路径（推荐）或绝对路径；file://、~、环境变量（如 $HOME）均不被识别
路径指向的必须是一个**目录**，不是 composer.json 文件本身；该目录下必须存在合法的 composer.json，否则 Composer 静默跳过
常见错误：Could not find a matching version of package vendor/name —— 八成是 repositories 没写对位置，或路径写成了 ./packages/my-lib/composer.json

本地包的 composer.json 必须有 name 和 version（哪怕写 dev-main）

Composer 不读取目录名或文件结构，只认 composer.json 里的 name 字段，且要求与 require 中写的完全一致（包括 vendor 前缀）。

Discussion Composer

围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par

下载

name 必须是 vendor/name 格式，例如 "myorg/utils"；写成 "utils" 或 "myorg/utils-dev" 都会匹配失败
version 字段建议设为 "dev-main"（Git 2.27+ 默认分支名）或 "dev-master"；若留空或格式非法，composer require 可能报错
require 时版本约束要对应：用 dev-main 就写 "myorg/utils": "dev-main"；若设了 "minimum-stability": "dev"，还得加 @dev 后缀，即 "myorg/utils": "dev-main@dev"
别在 require 字段直接写路径，例如 "myorg/utils": "./packages/my-lib" —— 这是语法错误，Composer 完全忽略

符号链接（symlink）不是默认就生效，而是有条件触发

Linux/macOS 下默认创建软链，Windows 默认复制；但无论哪一平台，都依赖系统权限和 Composer 版本支持。

Linux/macOS：需确保 symlink 系统调用可用（通常默认支持）；验证方式：ls -la vendor/myorg/utils 输出含 ->
Windows：需启用“开发者模式”或以管理员权限运行终端；否则 fallback 为复制行为
想强制复制（如 CI 环境）：在项目 composer.json 的 config 中加 "preferred-install": {"myorg/utils": "dist"}
想显式启用 symlink（尤其老版本 Composer）：在 path 仓库配置里加 "options": {"symlink": true}；注意此字段需 Composer ≥ 2.2
CI/CD 构建前务必移除 repositories 中的 path 条目，否则因路径不存在导致构建失败

改了本地包代码，为什么 vendor 里没更新？

composer install 不刷新已有链接，它只补缺；真正重建 symlink 的命令是 composer update vendor/name。

composer install 严格按 composer.lock 执行，只要链接已存在，就不会重新解析路径或检查本地改动
改完本地包代码后，必须运行 composer update myorg/utils（指定包名），才能重新读取本地 composer.json、校验 name、重建 symlink
避免无参数的 composer update：它会重算全部依赖，可能意外升级其他包，引入不兼容变更
首次引入用 composer require myorg/utils:dev-main，此时也会触发 symlink 创建（2026 年 9 月起所有稳定版 Composer 均支持）