如何让Composer完全离线工作？（建立本地依赖镜像）-composer-PHP中文网

如何让Composer完全离线工作？（建立本地依赖镜像）

穿越時空

发布： 2025-12-17 18:35:02

原创

186人浏览过

Composer 完全离线工作的核心是用 Satis 构建静态包镜像，需手动补全完整依赖树、使用稳定版本约束，并通过本地 HTTP 服务托管 packages.json 和 ZIP 包，再在项目中配置私有仓库地址并禁用 packagist.org。

如何让composer完全离线工作？（建立本地依赖镜像）

让 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，不再联网。

关键细节与避坑点

离线镜像容易失败，往往卡在几个隐性依赖上：

ListenLeap

AI辅助通过播客学英语

217

查看详情

必须包含所有递归依赖：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"。