本文详解为何使用本地Composer仓库（如Satis）时，composer install仅安装require/require-dev中显式声明的包，却忽略其深层依赖；核心原因在于仓库元数据不完整，尤其缺失require、conflict等关键字段，导致Composer无法构建完整依赖图。
本文详解为何使用本地composer仓库（如satis）时，`composer install`仅安装`require`/`require-dev`中显式声明的包，却忽略其深层依赖；核心原因在于仓库元数据不完整，尤其缺失`require`、`conflict`等关键字段，导致composer无法构建完整依赖图。
在基于 Composer 的 PHP 项目中，composer install 的行为高度依赖 composer.lock 文件与仓库提供的完整包元数据。当使用 Packagist（官方仓库）时，所有包的 composer.json 元信息（包括 require、conflict、replace、provide、autoload 等）均被完整索引并提供给 Composer 解析器，从而能准确推导出整个依赖树——例如 laravel/framework:9.19 显式声明了 "illuminate/container": "^9.0"，Composer 便会递归拉取其全部依赖。
但当你切换为本地仓库（如通过 Satis 搭建），问题往往不出在 ZIP 包内容本身，而在于 Satis 生成的仓库元数据（packages.json）是否完整映射了源包的全部约束字段。
✅ 正确行为：
composer install→ 读取composer.lock→ 根据 lock 中记录的包名+版本 → 向本地仓库请求该包的完整元数据 → Composer 解析其require字段 → 递归下载依赖
❌ 实际故障：本地仓库返回的元数据中require字段为空或缺失 → Composer 认为该包“无依赖” → 仅安装顶层 11 个包 →vendor/illuminate/*等关键依赖缺失 →Illuminate\Foundation\Application找不到 →artisan崩溃
? 根本原因：Satis 配置遗漏关键元数据字段
默认 Satis 配置（尤其是早期版本或简化模板）常只导出基础字段，例如：
// ❌ 错误的 satis.json 片段（仅导出 require & autoload）
{
"name": "my-private-repo",
"repositories": [{ "type": "vcs", "url": "https://git.example.com/pkg" }],
"output-dir": "web/",
"archive": { "directory": "dist", "format": "zip", "skip-dev": true },
"providers": ["*"],
"require-all": true
}
即使每个 ZIP 包内含合法 composer.json，Satis 不会自动提取并暴露其中的 require、conflict、replace 等字段到公开的 packages.json 元数据中。它仅按配置导出你显式允许的字段。
因此，若 satis.json 未启用元数据继承或未声明所需字段，laravel/framework 的元数据将变成：
{
"name": "laravel/framework",
"version": "9.19.0",
"dist": { /* ... */ },
"autoload": { /* ... */ }
// ⚠️ 缺失 "require": { "illuminate/container": "^9.0", ... }
}
→ Composer 视其为“零依赖包”，自然跳过安装 illuminate/* 系列。
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
✅ 正确解决方案：补全 Satis 元数据字段
需在 satis.json 中显式声明需继承的根级字段（即 composer.json 中影响依赖解析的核心字段）。推荐配置如下：
{
"name": "my-private-repo",
"repositories": [
{ "type": "vcs", "url": "https://git.example.com/pkg-a" },
{ "type": "vcs", "url": "https://git.example.com/pkg-b" }
],
"output-dir": "web/",
"archive": {
"directory": "dist",
"format": "zip",
"skip-dev": true,
"prefix-url": "https://repo.example.com/dist"
},
"providers": ["*"],
"require-all": true,
// ✅ 关键修复：强制导出所有影响依赖解析的字段
"config": {
"archive": {
"format": "zip"
}
},
// ✅ 必须显式列出需继承的元数据字段（Satis ≥ 2.0 支持）
"include-filters": [
"/^require$/",
"/^require-dev$/",
"/^conflict$/",
"/^replace$/",
"/^provide$/",
"/^suggest$/",
"/^autoload$/",
"/^type$/",
"/^extra$/"
]
}
? 提示：
include-filters是 Satis 2.x+ 的核心配置项，用于正则匹配源包composer.json中需透出的字段。务必包含require和require-dev（即使你的私有包不用require-dev，Laravel 等主流包依赖它）。
构建后验证元数据是否生效：
# 查看生成的 packages.json 中某包的元数据
curl -s https://repo.example.com/packages.json | jq '.packages["laravel/framework"][0].require'
# ✅ 应输出类似：{"illuminate/container": "^9.0", "php": "^8.0"}
⚠️ 补充注意事项
-
不要依赖 ZIP 内
composer.json：Composer 从仓库获取元数据时，完全不读取 ZIP 包内容，只消费packages.json中预生成的 JSON 结构。 -
避免
require-all: false+ 手动require：若禁用require-all，需为每个包单独配置require，极易遗漏；生产环境强烈推荐require-all: true+ 完整include-filters。 -
Windows 符号链接权限：若本地仓库含 symlink 包，确保 Satis 构建时使用管理员权限，否则
distZIP 可能损坏。 -
验证锁文件兼容性：修复元数据后，删除
composer.lock并重新运行composer install（而非update），以强制按新元数据重建依赖图。
? 快速诊断命令
遇到类似问题，立即执行以下检查：
# 1. 确认本地仓库是否返回了 require 字段 composer show laravel/framework --all | grep -A5 "requires" # 2. 检查当前仓库源（确认指向本地） composer config repositories.0.url # 3. 强制刷新元数据缓存（避免旧缓存干扰） composer clear-cache
总结：Composer 本地仓库不是“文件托管服务”，而是元数据服务。
require字段的缺失，本质是依赖图的断裂。补全satis.json中的include-filters，让require、conflict等字段透出，才是治本之策——这比调试autoload或重写repositories路径高效十倍。
