离线安装必须禁用 packagist.org,否则必联网;需三步:全局执行 composer config --global repo.packagist false、确保项目 composer.json 中无 packagist 条目、验证 install -v 不出现 repo.packagist.org 请求;artifact 仓库最稳,要求包命名严格、文件内容与 lock 中 shasum 一致;path 类型仅限本地开发联调,require 必须加 @dev。

离线安装必须禁用 packagist.org,否则必联网
哪怕你已经配了本地仓库,composer install 仍可能发出 DNS 请求或尝试连接 repo.packagist.org。根本原因是 Composer 默认启用 fallback 行为,只要没显式关掉官方源,它就会在查不到包时自动重试。
必须同时执行三步:
-
composer config --global repo.packagist false(全局关闭) -
composer config repo.packagist输出应为空,不能是composer https://packagist.org - 检查项目
composer.json的repositories字段,删掉任何指向https://packagist.org的条目
验证是否生效:运行 composer install -v,全程不应出现 Downloading https://repo.packagist.org/packages.json 或类似日志。
用 artifact 类型做纯离线部署最稳
artifact 是唯一真正“零网络探测”的仓库类型——它只读本地 .tar.gz 文件,不查元数据、不发 HEAD 请求、不校验远程签名。
关键约束很硬,错一个就失败:
- 压缩包命名必须严格为
vendor-name/package-name-version.tar.gz(如monolog/monolog-2.13.0.tar.gz) - 包内
composer.json的name和version必须与文件名完全一致(大小写、分隔符都不能差) - 所有包放在同一级目录下(如
/opt/artifacts/),不能有子目录嵌套 - 配置命令:
composer config repositories.offline '{"type":"artifact","url":"/opt/artifacts/"}'
注意:composer.lock 中的 dist.shasum 必须和实际解压后内容一致,否则校验失败直接中止,不会 fallback 到其他源。
使用 template.yaml 定义创建 Spotify Backstage 软件模板,包含 Scaffolder 操作,包括 fetch:template、publish:github 和 catalog:register。通过其 REST API 管理 Backstage 软件目录。
用 path 类型联调本地开发包,但仅限你手头有源码
path 类型跳过所有网络请求,直接读取本地目录里的 composer.json,适合你在写一个新包、边改边测的场景。
常见踩坑点:
- 路径必须是相对路径(如
./packages/my-utils),不能用/home/user/my-utils这类绝对路径 -
composer.json中必须声明"options": {"symlink": false},否则离线机上软链失效 -
require时必须加@dev标识,例如composer require my-utils/my-utils:@dev - 包的
name字段值必须和require写的完全一致(包括 vendor 名大小写)
这个方式不能用于部署,因为 composer install 在离线机上会尝试复制整个目录,而不是解压归档,体积大、不可控、难审计。
Satis 不是离线方案,而是镜像构建工具
很多人误以为 Satis 能直接在离线机上跑,其实不是。Satis 本身必须联网运行,用来批量抓取包、生成静态 packages.json 和 .zip 归档——它是个“打包机”,不是“运行时仓库”。
真正离线的部分只有两件事:
- 把 Satis 构建出的
web/目录(含packages.json+dist/)部署到内网 Web 服务(如 Nginx) - 项目中配置
"type": "composer", "url": "http://internal-packages/"并确保repo.packagist已关
如果你没 Web 服务,就别走 Satis 这条路;强行用 file:// 协议会导致部分版本解析失败,且 archive.prefix-url 无法生效——这是 Composer 底层限制,不是配置问题。

















