Composer本地包如何引入调试？Path路径设置教程-composer-PHP中文网

本地包引入失败主因是repositories配置错误：必须置于composer.json根级、url为合法相对路径、name与本地包严格一致，且本地包需有Git仓库并启用symlink选项。

composer本地包如何引入调试？path路径设置教程

本地包引入失败，90%不是网络或缓存问题，而是 Composer 根本没“看见”你的目录——repositories 写错位置、url 路径不合法、name 不匹配，三者任一出错都会静默跳过，连错误都不报。

repositories 必须写在 composer.json 根级

Composer 只从项目根目录 composer.json 的最外层读取 repositories 字段，其他任何位置都无效：

不能塞进 require、autoload、extra 或 config 里
不能写成 "repositories": {"my-pkg": {...}}（必须是数组）

正确写法是：

{
  "repositories": [
    {
      "type": "path",
      "url": "./packages/my-utils"
    }
  ],
  "require": {
    "mycompany/utils": "dev-main"
  }
}

url 必须是相对路径且指向含 composer.json 的目录

url 不接受绝对路径、~、file:// 或尾部斜杠，只认以 ./ 或 ../ 开头的相对路径：

❌ "url": "packages/my-utils"（缺 ./ 前缀）
❌ "url": "/home/user/pkg"（绝对路径，静默忽略）
❌ "url": "../my-pkg/"（末尾 / 会导致整个仓库被跳过）
✅ "url": "../my-pkg" 或 "url": "./packages/utils"
路径必须指向一个**存在合法 composer.json 的目录**，不是文件本身

name 和 version 必须严格对齐

本地包的 composer.json 中 name 和 version（或分支名）必须与 composer require 命令完全一致：

Academic Composer Upload

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

下载

name 大小写、分隔符（仅短横线 -）、vendor 名全部敏感："acme/utils" ≠ "Acme/utils" ≠ "acme_utils"
本地包需有 Git 仓库（至少 git init && git add . && git commit -m "init"），否则 dev-main 等分支别名无法解析
执行命令时必须显式指定版本：composer require acme/utils:dev-main，不能省略或写 *
若用 @dev，项目 composer.json 需提前设 "minimum-stability": "dev"

symlink 生效与否，关键在本地包自己的 composer.json

符号链接是否真正建立，不取决于主项目配置，而取决于本地包目录下的 composer.json 是否声明了 options：

必须在**本地包自己的 composer.json** 中加：
```
"options": {
  "symlink": true
}
```
Windows 用户必须以管理员身份运行终端，否则 symlink 创建失败且无提示
验证是否成功：ls -la vendor/acme/utils（Linux/macOS）应显示 ->；dir vendor\acme\utils（Windows）应看到 JUNCTION
改完本地代码后，必须运行 composer update acme/utils，install 不刷新已有链接

最容易被忽略的是 autoload 映射更新和 symlink 的归属权——composer dump-autoload 要手动执行，而 symlink 的开关权限不在主项目，而在本地包自身。路径写对、name 对齐、Git 提交完成，三者缺一不可，少一个环节，就只剩 Could not find package 这句沉默的拒绝。