如何使用Composer配置本地包自动发现-composer-PHP中文网

必须显式配置path仓库并指定dev-main版本才能自动发现本地包；需在主项目composer.json的repositories中声明type为path、url为相对路径，本地包composer.json含匹配name和dev-main，并启用symlink选项确保代码实时生效。

如何使用composer配置本地包自动发现

Composer 自动发现本地包需要启用 `path` 类型仓库

Composer 默认不会扫描项目目录下的任意文件夹作为包来源，必须显式声明一个 path 类型的仓库，并指向本地路径。否则即使包结构正确、composer.json 存在，composer require 也会报 Could not find package xxx。

实操建议：

Workflow Decomposer

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

下载

在项目根目录的 composer.json 中添加 repositories 字段，类型设为 path，url 填相对或绝对路径（推荐相对路径，如 ../my-local-package）
url 路径下必须包含有效的 composer.json，且其中 name 字段需符合 vendor/name 格式（例如 "name": "acme/utils"）
路径不能以 ./ 开头（Composer 会忽略），也不能是符号链接目标未被信任的路径（部分版本会跳过 symlinks）

require 本地包时要指定开发版稳定性（如 `dev-main`）

Composer 对本地 path 包默认不启用“自动匹配分支”，它只认 composer.json 中定义的 version 或按分支名解析的开发版别名。如果你本地包用的是 main 分支，直接 composer require acme/utils 会失败。

实操建议：

运行 composer require acme/utils:dev-main（或 dev-master，取决于分支名）
确保本地包的 composer.json 中没有设置 "minimum-stability": "stable"，否则会拒绝加载 dev- 前缀的版本
若想省略版本号，可在本地包中加 "version": "dev-main"，但该字段仅用于本地测试，上线前必须删掉——它会被 Composer 忽略或导致 packagist 同步冲突

修改本地包代码后需执行 `composer update` 才能生效

不同于 symlink 方式（如 composer install --prefer-source 配合 path 仓库可启用软链），默认 path 仓库行为是「拷贝」：Composer 会把整个包目录复制进 vendor/。因此改了本地源码，vendor/ 里的副本不会自动同步。

实操建议：

启用 symlink 模式：在 repositories 条目中增加 "options": {"symlink": true}
或者更直接：用 composer update acme/utils --with-dependencies 强制重拉（注意这会触发 autoload 重建）
验证是否生效：检查 vendor/acme/utils 是否为符号链接（Linux/macOS）或 Junction（Windows），不是普通文件夹

常见错误：`Package acme/utils has a PHP requirement incompatible with your PHP version`

这个报错往往不是 PHP 版本真不兼容，而是 Composer 在解析本地 path 包时，先读取了它的 composer.json，发现其中 require.php 指定的版本范围（如 ^8.2）和当前环境不匹配，就直接中断，甚至不提示具体哪一行出问题。

排查要点：

确认本地包的 composer.json 中 require.php 值与你当前 php -v 输出一致（例如本地是 PHP 8.1，就别写 ^8.2）
如果只是临时开发，可临时改成 "php": "*"，但切记提交前改回
该检查发生在 composer require 和 composer update 阶段，composer validate 不会报此错，容易误判