本地包需满足五项要求:1. composer.json 的 name 必须为小写两段式(如 "acme/utils");2. repositories 必须置于主项目 composer.json 根级且为数组;3. path 类型 url 必须是含 composer.json 的相对路径目录;4. 该目录须已 git init 并至少一个 commit;5. autoload、文件路径、命名空间三者必须严格对齐,且需运行 composer dump-autoload。

本地包必须有合法的 composer.json,且 name 是 vendor/name 格式
Composer 不认目录名、不猜包名,只严格比对本地包 composer.json 里的 name 字段。它必须是两段式、小写字母+数字+连字符+斜杠的格式,例如 "acme/utils" 或 "myorg/api-client"。
常见错误包括:
-
"utils"(缺 vendor 段) -
"Acme/Utils"(大写,与require中写的"acme/utils"不匹配) -
"acme-utils"(用短横而非斜杠,不是合法包名)
如果 name 不合法或不一致,composer require 会静默跳过该路径,甚至不报错。
repositories 必须写在主项目 composer.json 根级,且是数组
配置无效的最常见原因:把 repositories 塞进 config、extra 或子目录里,或者写成对象而非数组。
正确写法只有一种:
"repositories": [
{"type": "path", "url": "./packages/utils"}
]
注意:
-
url必须是相对路径,以./或../开头;"packages/utils"(缺./)会被忽略 -
url指向的是**含composer.json的目录**,不是文件,也不是绝对路径(/home/xxx、C:xxx全部静默失败) - 该目录下必须已执行
git init并至少有一个 commit,否则 Composer 直接跳过
版本号要和分支/标签对齐,且主项目需设 minimum-stability
本地包没打 tag 时,只能用分支名作为版本,如 "dev-main"、"dev-develop"。此时主项目 composer.json 必须显式声明:
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
"minimum-stability": "dev", "prefer-stable": true
否则 dev-main 会被稳定性策略过滤掉,composer require acme/utils:dev-main 报 “Could not find package”。
另外,本地包自己的 composer.json 中可不写 version 字段——Composer 会自动从 Git 分支或 tag 推断,但前提是 Git 仓库状态正常。
autoload 映射必须和文件路径、命名空间三者完全对齐
装上包 ≠ 能用类。90% 的 Class not found 错误出在这里。
检查三点是否一致:
- 本地包
composer.json中autoload.psr-4的前缀,如"Acme\Utils\": "src/" - 类文件实际路径,如
src/Http/Client.php - 该文件顶部
namespace声明,如namespace AcmeUtilsHttp;
三者任一错位,自动加载器就拼不出正确路径。改完后别忘了在主项目运行 composer dump-autoload 刷新映射——这步不能省,也不需要加 -o。
最容易被忽略的是:本地包目录必须已初始化 Git 且有 commit,否则 Composer 根本不扫描;还有 Windows 下路径含中文或空格时,即使其他都对,也可能因系统层限制导致 symlink 创建失败,调试时建议先用纯英文路径验证逻辑通不通。

















