Composer 完全离线工作的核心是用 Satis 构建静态包镜像，需手动补全完整依赖树、使用稳定版本约束，并通过本地 HTTP 服务托管 packages.json 和 ZIP 包，再在项目中配置私有仓库地址并禁用 packagist.org。
让 Composer 完全离线工作，核心是把所有需要的包（包括依赖树中每一层的包、元数据和 ZIP 文件）提前下载并组织成一个本地可替代 Packagist 的镜像服务。不是简单缓存，而是构建一个功能等价的私有仓库。
用 Satis 构建静态包镜像
Satis 是官方推荐的轻量级静态镜像工具，适合离线场景。它会拉取指定包的源码 ZIP、生成 packages.json 和完整目录结构，最终产出纯静态文件，用任意 HTTP 服务器（如 nginx、Apache 或 Python 的 http.server）就能提供服务。
- 新建
satis.json，明确列出你项目实际用到的所有顶层包（含require-dev），例如：{ "name": "my-offline-mirror", "homepage": "http://localhost/satis", "repositories": [ { "type": "composer", "url": "https://packagist.org" } ], "require-all": false, "require": { "monolog/monolog": "^2.0", "symfony/console": "^5.4" }, "archive": { "directory": "dist", "format": "zip", "skip-dev": false } } - 运行
php bin/satis build satis.json web/（需先用 Composer 安装 Satis）。这一步会下载所有依赖、生成packages.json和 ZIP 包，全部放进web/目录。 - 把
web/整个目录复制到离线机器，用python3 -m http.server 8000启动本地服务（地址如http://127.0.0.1:8000）。
在项目中切换到本地镜像
修改项目的 composer.json，禁用 Packagist 并指向你的本地服务：
- 添加
"repositories"块，优先级高于默认源："repositories": [ { "type": "composer", "url": "http://127.0.0.1:8000" } ], - 关闭 Packagist 默认源：
"packagist.org": false
- 运行
composer clear-cache && composer update --no-interaction。Composer 将只从本地 HTTP 服务读取元数据和 ZIP，不再联网。
关键细节与避坑点
离线镜像容易失败，往往卡在几个隐性依赖上：
-
必须包含所有递归依赖：Satis 默认只处理
require列表里的直接依赖。如果某个包的composer.json里声明了require，但你没显式写进satis.json的require，Satis 不会自动拉取——除非启用"require-all": true（不推荐，会镜像整个 Packagist 子集）；更稳妥的是先在线运行composer install，再用composer show --tree导出完整依赖树，手动补全到satis.json。 -
ZIP 包权限与路径：Satis 生成的
dist/下 ZIP 文件需确保 Web 服务器能读取；路径不能含空格或特殊字符，否则 Composer 解压失败。 -
版本约束要具体：避免使用
"*"或"dev-master"，这类动态版本在离线时无法解析；统一用稳定版约束，如"^2.0"或固定版本"2.0.2"。
替代方案：Toran Proxy（适合长期维护）
如果团队需频繁更新镜像、支持私有包或 Web 管理界面，Toran Proxy 是更成熟的闭源方案（已停止维护，但旧版仍可用）。它作为代理缓存所有请求，首次联网后后续完全离线。不过对纯一次性离线部署，Satis 更轻量、无外部依赖、透明可控。
基本上就这些。核心逻辑很清晰：用工具把“在线仓库”完整快照下来 → 换个地址托管 → 让 Composer 只认这个地址。不复杂但容易忽略递归依赖和版本锁定，多跑一次 composer show --tree 能省掉大半问题。
