答案是:90%失败源于三个硬性条件缺一不可——主项目composer.json声明type为path的repositories、本地包目录含合法composer.json、其name字段与require字符串逐字完全一致(大小写、短横线、vendor名全匹配)。

直接在主项目 composer.json 里加 repositories + require 就能用本地包,但 90% 的失败不是配置不会写,而是三个硬性条件漏掉一个:主项目声明了 path 类型仓库、本地包目录下有合法 composer.json、且其中 name 字段和 require 里的字符串**逐字完全一致**。
本地包的 composer.json 必须合法且含正确 name
Composer 不会帮你纠错或容错——它只认 name 字段的原始值。这个值就是你在主项目中 require 时要写的完整字符串(包括 vendor 名)。
-
name只能用小写字母、数字、短横线-,不能用下划线_、大写字母或空格 - 必须是合法 JSON:无尾逗号、全双引号、字段名不拼错(比如写成
"nmae"就静默失效) - 示例正确写法:
"name": "acme/utils";错误写法:"name": "Acme/Utils"或"name": "acme_utils" - 如果本地包还没初始化 Git,建议显式加
"version": "dev-main",否则 Composer 可能无法推断分支版本
主项目 composer.json 的 repositories 配置要点
这个配置告诉 Composer:“别只去 Packagist 找,我本地这个路径里也有个包”。但它只对当前项目生效,不能写在本地包自己的 composer.json 里。
-
url值必须是**相对于主项目composer.json文件所在目录的路径**,比如本地包在上层目录:"../my-local-package";末尾不能带/ - 绝对路径也行,但不推荐;
~/my-pkg或$HOME/my-pkg这类带环境变量的写法会被忽略 - Windows 下路径含中文、空格或 OneDrive 同步文件夹,可能导致读取失败,优先用纯英文路径
- 必须写成
"type": "path",不是"type": "package"或其他类型
为什么 require 写了却报 Could not find package
这不是网络问题,也不是 Composer 没运行,而是解析阶段就跳过了你的本地源——因为版本约束没匹配上。
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
- 别写
"acme/utils": "*"或"acme/utils": "^1.0":这些会绕过path源,退回到 Packagist 查找 - 必须写明确的开发分支版本,如
"acme/utils": "dev-main"(Git 当前分支是main)或"acme/utils": "dev-master" - 确认本地包当前分支:
cd ../my-local-package && git branch --show-current - 如果本地包没 Git,就在它的
composer.json里加"version": "dev-main",再在主项目 require 对应版本
改了本地包代码,主项目没更新?先看是不是 symlink 失效了
Composer 默认尝试创建符号链接,但失败时会静默 fallback 到复制(copy)模式——这时你改的是源码,vendor 里还是旧副本,最隐蔽也最常被忽略。
- 关键不在主项目配什么,而在**本地包自己的
composer.json是否含"options": {"symlink": true}** - Windows 下必须以管理员身份运行终端,否则 symlink 创建失败且无提示
- Docker 场景需加
--cap-add=SYS_ADMIN,且挂载方式要支持 symlink - 验证是否真用了 symlink:
ls -la vendor/acme/utils(Linux/macOS)或dir vendor\acme\utils(Windows),看到箭头或JUNCTION才算成功 - autoload 不生效?执行
composer dump-autoload -o强制刷新自动加载映射
真正麻烦的从来不是怎么写配置,而是路径、name、版本三者之间那点“必须完全一致”的脆弱契约——少一个字符、多一个斜杠、大小写差一点,都会让 Composer 直接无视那个本地包。










