离线包不能仅靠配置cache-files-dir实现团队共享,因其仅为本地缓存路径,不提供服务发现能力;团队成员需统一使用artifact仓库并显式配置repositories,同时确保composer.lock中dist.url为可解析路径且提交至Git。

离线包无法“配置”后自动共享,必须显式声明本地路径仓库并确保 ZIP 包可被 composer install 直接读取;只改 cache-dir 或加 COMPOSER_DISABLE_NETWORK=1 都不生效。
为什么不能只配 cache-files-dir 让团队共用?
cache-files-dir 是全局缓存路径,它只影响当前机器上 Composer 下载 ZIP 包时的存放位置,不提供服务发现能力。团队成员各自机器上的 cache-files-dir 互不可见,也无法被他人 composer install 自动识别——它不是仓库,只是临时落盘目录。
- 即使你把
/path/to/cache/files打包发给同事,他们不手动执行composer config --global cache-files-dir /that/path/files,Composer 就不会去读 - 该路径下 ZIP 文件名含哈希(如
monolog-monolog-6a8c4b5.zip),没有packages.json元数据,无法被当作仓库索引 - 多人环境里权限、路径拼写、PHP 用户(如
www-datavsroot)不一致,stat()失败就静默 fallback 到联网
正确做法:用 path 类型仓库 + 预打包 ZIP
让团队离线安装同一套包,本质是搭建一个“静态文件仓库”,核心是让每个项目都能通过 repositories 显式指向 ZIP 文件所在目录,并由 Composer 按 dist.url 规则加载。
使用 template.yaml 定义创建 Spotify Backstage 软件模板,包含 Scaffolder 操作,包括 fetch:template、publish:github 和 catalog:register。通过其 REST API 管理 Backstage 软件目录。
- 先在联网机把所有依赖 ZIP 包导出到统一目录,例如
/srv/composer-mirror/zips/,结构为:monolog/monolog/2.10.0.0/monolog-monolog-6a8c4b5.zip - 在团队共用的模板
composer.json中添加仓库配置:"repositories": [ { "type": "package", "package": { "name": "monolog/monolog", "version": "2.10.0", "dist": { "url": "/srv/composer-mirror/zips/monolog/monolog/2.10.0.0/monolog-monolog-6a8c4b5.zip", "type": "zip", "shasum": "6a8c4b5..." } } } ](注意:type: "package"手动定义单个包,适合少量关键依赖;若包多,应改用type: "artifact") - 更实用的是
artifact仓库:把整个zips/目录设为 artifact 根,Composer 会自动扫描子目录匹配vendor/name/version/*.zip——只需配一次:"repositories": [ { "type": "artifact", "url": "/srv/composer-mirror/zips/" } ] - 该目录需对所有开发者可读(
chmod -R a+r /srv/composer-mirror/zips),且路径必须是绝对路径或相对于项目根目录的固定相对路径(不推荐后者,易错)
artifact 仓库的三个硬性限制
artifact 是离线共享最接近“开箱即用”的方案,但它有明确边界,踩中任意一条就会失败:
- 只支持顶层
require的包,不递归解析子依赖的 ZIP —— 若monolog/monolog依赖psr/log,而后者没出现在zips/下,composer install仍会报错“Package not found”,除非你也把psr/log的 ZIP 放进去 - ZIP 文件必须带完整
dist.shasum,且与composer.lock中记录的一致;用composer archive生成时,源包composer.json必须含"version"字段,否则 ZIP 名称和哈希无法对齐 - 不校验 PHP 版本或扩展,但若 ZIP 内含
ext-redis调用,目标机没装扩展,运行时报错而非安装时报错 —— 这类兼容性得靠platform配置提前约束
团队落地时最容易忽略的两件事
共享离线包不是拷个目录就完事,两个细节不处理,90% 的人会在第一次 composer install 时失败:
-
composer.lock必须提交进 Git,且其中每个包的dist.url必须是相对路径(如zips/monolog/monolog/2.10.0.0/monolog-monolog-6a8c4b5.zip)或能被所有机器解析的路径;如果锁文件里还留着https://开头的 URL,COMPOSER_DISABLE_NETWORK=1会让 Composer 直接退出 - 首次在新机器运行前,必须清掉干扰项:
composer config --global --unset cache-dir和composer config --global --unset cache-files-dir,否则旧配置会覆盖 artifact 查找逻辑,导致静默走默认网络路径










