本文详解为何使用本地Composer仓库（如Satis）时composer install仅安装顶层包而忽略其子依赖，并揭示根本原因在于仓库元数据缺失——特别是require、conflict等关键字段未被正确导出，导致Composer无法构建完整依赖图。
本文详解为何使用本地composer仓库（如satis）时`composer install`仅安装顶层包而忽略其子依赖，并揭示根本原因在于仓库元数据缺失——特别是`require`、`conflict`等关键字段未被正确导出，导致composer无法构建完整依赖图。
在基于 Composer 的 PHP 项目中，composer install 的行为高度依赖 composer.lock 文件与仓库提供的完整包元数据。当你将 Packagist 切换为本地仓库（例如通过 Satis 搭建的私有源）后出现“只装了 require 里的 11 个包，却不装它们各自的依赖（如 illuminate/support、symfony/http-foundation 等）”，进而导致 Class "Illuminate\Foundation\Application" not found 这类致命错误——这并非 Composer 本身故障，而是本地仓库元数据不完整所致。
? 根本原因：仓库未提供可解析的依赖声明
Packagist 是一个“智能仓库”：它不仅托管 ZIP 包，更会动态解析每个包的 composer.json，提取 require、conflict、replace、provide、autoload 等字段，生成标准化的 JSON 元数据（即 packages.json 中的条目），供 Composer 构建完整的依赖图。
而许多本地仓库方案（尤其是早期 Satis 配置）默认仅导出部分字段。正如问题答案所指出：
“Satis 不读取 ZIP 包内的
composer.json，而是读取你satis.json中定义的元数据。”
如果你的 satis.json 仅显式配置了：
{
"name": "my-private-repo",
"homepage": "http://localhost/",
"repositories": [{ "type": "vcs", "url": "https://github.com/myorg/package-a" }],
"output-dir": "web",
"archive": { "directory": "dist", "format": "zip", "skip-dev": true },
"providers": ["*"]
}
并未启用元数据继承或未补全关键字段映射，Satis 在生成 packages.json 时，可能只写入了 name、version、dist 和基础 autoload，却完全遗漏了 require 字段——这意味着 Composer 在解析 laravel/framework:^9.19 时，看到的元数据中“它不依赖任何其他包”，于是跳过所有下游依赖的安装。
✅ 正确配置：确保 Satis 导出全部必需元数据字段
Satis 支持通过 providers 和自定义 require 映射来增强元数据完整性。关键配置如下（satis.json 示例）：
{
"name": "My Private Repository",
"homepage": "http://localhost/",
"repositories": [
{ "type": "vcs", "url": "https://github.com/laravel/framework" },
{ "type": "vcs", "url": "https://github.com/guzzlehttp/guzzle" }
],
"require-all": true,
"require-dependencies": true,
"require-dev-dependencies": false,
"output-dir": "web",
"archive": {
"directory": "dist",
"format": "zip",
"skip-dev": true,
"absolute-directory": false
},
"providers": ["*"],
"config": {
"process-timeout": 3600
}
}
⚠️ 必须启用的两个核心选项：
-
"require-all": true：强制 Satis 扫描并包含所有require、require-dev、conflict、replace、provide、suggest字段； -
"require-dependencies": true：确保对每个包的依赖项也递归解析并收录进仓库元数据。
执行构建命令时，务必使用：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
php bin/satis build satis.json web/
构建完成后，检查生成的 web/packages.json 中任意一个包（如 laravel/framework）的条目，确认其包含类似结构：
"laravel/framework": {
"9.52.16": {
"name": "laravel/framework",
"version": "9.52.16",
"require": {
"php": "^8.0.2",
"ext-json": "*",
"ext-mbstring": "*",
"doctrine/inflector": "^2.0",
"egulias/email-validator": "^3.1",
"laravel/serializable-closure": "^1.0",
"league/mime-type-detection": "^1.9",
"monolog/monolog": "^2.0",
"nesbot/carbon": "^2.62.1",
"nunomaduro/termwind": "^1.15",
"psr/container": "^1.1|^2.0",
"psr/event-dispatcher": "^1.0",
"psr/log": "^1.0|^2.0|^3.0",
"psr/simple-cache": "^1.0|^2.0|^3.0",
"ramsey/uuid": "^4.2.2",
"symfony/console": "^6.0",
"symfony/dotenv": "^6.0",
"symfony/error-handler": "^6.0",
"symfony/http-foundation": "^6.0",
"symfony/http-kernel": "^6.0",
"symfony/mailer": "^6.0",
"symfony/mime": "^6.0",
"symfony/process": "^6.0",
"symfony/routing": "^6.0",
"symfony/translation": "^6.0",
"symfony/uid": "^6.0",
"symfony/var-dumper": "^6.0",
"tijsverkoyen/css-to-inline-styles": "^2.2.3",
"vlucas/phpdotenv": "^5.4.1",
"voku/portable-ascii": "^2.0"
},
"autoload": { ... },
"conflict": { ... },
"provide": { ... }
}
}
✅ 若 require 字段存在且内容完整，则 composer install 将能正确解析整棵依赖树。
? 验证与调试步骤（推荐流程）
-
清空环境
rm -rf vendor composer.lock
-
强制刷新仓库缓存（避免 Composer 读取旧缓存）
composer clear-cache
-
启用详细日志，定位解析断点
composer install -vvv 2>&1 | grep -A5 -B5 "resolving.*laravel/framework"
观察是否出现
Skipping package laravel/framework: no require entries found类提示。 比对元数据来源
运行composer show laravel/framework --all（先用 Packagist）与composer show laravel/framework --all -d http://localhost/（本地源），对比requires列表是否一致。
⚠️ 注意事项与最佳实践
-
不要手动编辑
packages.json：所有元数据应由 Satis 自动推导，手工维护极易出错且不可持续； -
禁用
--no-suggest或--no-dev除非明确需要：这些参数会抑制依赖发现； -
composer install永远以composer.lock为准：若 lock 文件是用 Packagist 生成的，切到本地源后必须删除并重建，否则 Composer 仍按旧依赖图安装； -
替代方案考虑
toran-proxy或Private Packagist：它们对元数据兼容性处理更鲁棒，适合企业级场景； -
安全提醒：本地仓库若未开启签名验证（
signing-key），将失去 Composer 2.5+ 的供应链完整性保护，建议配合composer config --global http-basic.repo.example.com token $TOKEN实现认证访问。
✅ 总结
Composer 本地仓库“只装顶层包”的本质，是元数据链断裂——不是 ZIP 缺失，而是 packages.json 中 require 字段为空或不全。解决路径唯一且明确：通过 satis.json 启用 require-all 与 require-dependencies，确保 Satis 完整继承并发布每个包的全部依赖声明。配置生效后，composer install 将恢复标准行为：下载 laravel/framework → 解析其 30+ 个 require 项 → 递归安装 symfony/http-kernel、monolog/monolog 等全部子依赖 → 最终成功加载 Illuminate\Foundation\Application。这不仅是技术配置问题，更是对 Composer 依赖解析机制的一次深度认知升级。
