Composer如何用path引本地包_symlink加载要点-composer-PHP中文网

composer默认不为path仓库创建symlink，必须在repositories中为对应仓库配置"options": {"symlinks": true}，否则会硬拷贝；同时需确保本地包name/version与require严格匹配，且系统支持符号链接。

composer如何用path引本地包_symlink加载要点

默认情况下，composer install 不会为 path 类型仓库自动生成符号链接（symlink），除非显式启用 symlinks 选项。这是最常被忽略的配置点。

在 composer.json 的 repositories 中定义 path 仓库时，必须把 options → symlinks 设为 true

示例配置：

{
  "repositories": [
    {
      "type": "path",
      "url": "../my-local-package",
      "options": {
        "symlinks": true
      }
    }
  ]
}

若省略 "symlinks": true，Composer 会直接拷贝源码（hard copy），而非创建 symlink —— 这会导致本地修改不实时生效

Composer 要求 path 包的 name 和 version 字段，与根项目 require 中声明的完全一致，否则会跳过 symlink 并报错或静默 fallback 到 dist 包。

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。

下载

require 写的是 "vendor/name": "dev-main"，那本地包的 composer.json 就必须有 "name": "vendor/name" 且 "version": "dev-main"（或使用 "branch-alias" 指向 dev-main）
如果本地包没写 version，Composer 会尝试从 Git 分支推断，但不可靠；建议显式写 "version": "dev-main" 或 "version": "1.x-dev"
Windows 下路径大小写不敏感，但 name 仍需严格匹配（如 acme/utils ≠ Acme/utils）

即使配置正确，symlink 仍可能因环境限制失败，错误通常不明显，需查 composer install -v 输出或检查 vendor/ 下对应目录是否为真实文件夹而非链接。

Linux/macOS：执行用户对 vendor/ 目录无写权限，或 fs.symlink 被 PHP 禁用（检查 disable_functions）
Windows：需启用开发者模式或以管理员身份运行终端（尤其 Win10 1703+），否则 symlink 调用直接被系统拒绝
本地包目录是 Git 工作区，但当前分支为 detached HEAD 或未跟踪文件过多，Composer 可能拒绝 symlink（认为状态不安全），可临时切到命名分支再试
路径含空格或中文？尽量避免——某些 Composer 版本（如 2.2.x）在解析 url 时对空格转义不稳定

别只信 composer install 的成功提示，手动确认才是关键。

进入 vendor/vendor-name/package-name，执行 ls -la（macOS/Linux）或 dir（Windows CMD）看是否指向外部路径
修改本地包源码，然后在主项目中调用对应类方法，观察变更是否立即生效（无需重新 install）
如果改了代码却没反应，先运行 composer dump-autoload —— symlink 存在但 autoloader 缓存未更新，也会“看起来没生效”
注意：IDE（如 PHPStorm）可能缓存文件路径，需刷新项目或重启索引

真正卡住人的往往不是配置语法，而是 symlinks 在不同系统上的权限模型差异、Git 工作区状态的隐式约束，以及 Composer 对 version 字段的强校验逻辑——这些点不打印错误，但会让 symlink 彻底静默失效。