Composer本地文件夹仓库需在项目composer.json中配置"type": "path"仓库并指向含合法composer.json的包目录，每个包必须明确定义name和version字段，不支持自动扫描无元数据的文件夹。
本地文件夹作为 Composer 仓库的正确配置方式
Composer 本身不支持直接“扫描文件夹批量安装包”，必须显式声明每个包的 name、version 和 dist 路径。所谓“本地文件夹仓库”，本质是用 path 类型仓库 + 正确的 composer.json 元数据驱动，不是自动发现机制。
核心前提是：每个待安装的包目录下必须有合法的 composer.json，且其中至少包含 name（格式如 vendor/package-name）和 version（或使用 dev-main 等开发分支别名）。
- 不能把一堆没
composer.json的 PHP 文件夹丢进去就指望 Composer 识别为包 -
path仓库只做路径映射，不校验包内容合法性；但安装时会读取目标目录下的composer.json，缺失关键字段会报错 - 推荐统一用
"type": "path"仓库，而非尝试伪造packagist镜像或改写repositories类型为composer
在项目根目录的 composer.json 中声明 path 仓库
不要试图在全局 ~/.composer/config.json 里配——那会影响所有项目，且无法按需启用。应该在当前项目的 composer.json 中添加 repositories 块，指向本地包所在父目录。
例如你的本地包都放在 ./packages/ 下，结构如下：
my-project/
├── composer.json
└── packages/
├── my-utils/
│ └── composer.json ← 内容含 "name": "acme/my-utils", "version": "1.0.0"
└── api-client/
└── composer.json ← 内容含 "name": "acme/api-client", "version": "0.5.0"
则项目 composer.json 的 repositories 应写成：
{
"repositories": [
{
"type": "path",
"url": "./packages/*"
}
],
"require": {
"acme/my-utils": "^1.0",
"acme/api-client": "^0.5"
}
}
-
url支持通配符*，但仅限于单层目录匹配；不能写./packages/** - 多个包共用一个
path仓库声明即可，无需为每个包单独写一条repository - 如果包名含大写字母或特殊字符，确保
name字段完全一致（Composer 对 name 大小写敏感）
安装时触发 symlink 而非拷贝的条件
默认情况下，path 类型仓库会创建符号链接（symlink），方便边开发边测试。但这个行为依赖两个前提同时满足：
- 操作系统支持 symlink（Windows 需启用开发者模式或以管理员运行 CMD）
- 未设置
COMPOSER_DISCARD_CHANGES=1或未在config中禁用preferred-install - 目标包目录不在
vendor/内（否则 Composer 会拒绝 symlink 防循环）
若看到包被复制进 vendor/ 而非链接，先检查：
composer config --list | grep preferred-install
如果输出含 preferred-install: {"*": "dist"}，说明全局或项目配置强制走 dist 安装。临时修复方法：
composer config preferred-install '{"*": "source"}'
composer install
常见错误：Package not found 或 Could not find package
这类报错几乎都源于元数据不匹配，而不是路径问题。典型原因包括：
-
packages/my-utils/composer.json里name写成了my-utils（缺 vendor 段），但require写的是"acme/my-utils" - 包目录名是
my-utils，但composer.json里name是acme/utils，两者不一致 - 执行
composer require acme/my-utils时，该包尚未提交到 Git（path仓库不依赖 Git，但如果你误配了vcs类型就会卡在这里） - 用了
composer update acme/my-utils却没先在require里声明，导致 Composer 不知道要拉哪个版本
调试技巧：运行 composer show --all 可列出所有已知包（含 path 仓库中的），确认名字和版本是否出现在列表中。没出现，说明 composer.json 有硬伤或路径未被识别。
真正麻烦的不是配置，而是每个包的 composer.json 必须手工维护 name/version —— 没有自动化捷径，也别信“一键生成仓库”的脚本，它们只是帮你批量写 composer.json，绕不开元数据定义这一步。
