composer require 默认不强制走 dist 下载,因它依赖包是否声明 dist 字段、版本约束类型及 lock 文件记录的安装方式;即使加 --prefer-dist,若 dist 不可用也会静默回退到 source。

composer require 为什么没走 dist 下载
因为 composer require 默认不强制 dist,它依赖包自身是否声明了 dist 字段、当前约束是否允许(比如不是 dev-master)、以及本地 composer.lock 是否已记录 source 安装方式。即使你加了 --prefer-dist,若包没提供 dist.url 或网络无法访问该 URL,Composer 仍会静默回退到 source(git clone)。
如何让 require 强制只走 dist(且失败时不 fallback)
严格来说,Composer 没有“强制仅 dist”的开关——但你可以组合策略,让 dist 成为唯一可行路径:
- 确保目标包有可用的
dist:运行composer show vendor/package version -s,确认输出中包含非空的dist.url和dist.type(如zip) - 显式禁用 source 路径:在项目级
composer.json的config段添加"preferred-install": {"*": "dist"},这比命令行参数更稳定 - 删掉可能干扰的锁文件:执行前删除
composer.lock和vendor/,避免旧 lock 记录 source 安装痕迹 - 绕过 packagist.org 元数据污染:若用私有源,必须设
"packagist.org": false并把私有源放在repositories数组首位,否则 Composer 仍可能从官方源拿到不含dist的元数据
常见失效场景与验证方法
即使配置正确,require 仍可能走 source,典型原因包括:
使用 template.yaml 定义创建 Spotify Backstage 软件模板,包含 Scaffolder 操作,包括 fetch:template、publish:github 和 catalog:register。通过其 REST API 管理 Backstage 软件目录。
-
dist.url指向 GitHub API(如https://api.github.com/...),而内网无法解析或访问——用curl -I测该 URL 是否返回 200 或 302 到真实 zip - 包是
dev-开头的开发版约束(如"dev-feature/x"),这类版本默认无dist,加--prefer-dist无效 - 私有 Git 仓库未启用 archive 功能(如 GitLab 未勾选 “Allow downloading project archives”),
dist字段为空 - SELinux 或文件权限阻止 Nginx 对
dist/目录下 ZIP 文件的 GET 访问(尤其在 Satis 私有源场景)
验证是否真走了 dist:运行 composer require vendor/package --prefer-dist -v,日志中出现 Downloading https://.../xxx.zip 才算成功;若看到 Cloning into 'vendor/vendor/package',说明 fallback 已发生。
私有源环境下 dist 下载失败的核心卡点
企业内网部署 Satis 后,require 仍报 404 或超时,90% 是因为 Web 服务没对齐三个硬性条件:
- Nginx 的
root必须精确指向 Satis 的output-dir(如root /var/www/satis/web;),不能多一层或少一层 - 必须显式声明 JSON MIME 类型:
types { application/json json; },否则packages.json返回text/plain,Composer 拒绝解析 - 私有源 URL 必须以
/结尾(如"url": "https://pkgs.internal/"),否则 Composer 会拼出错误路径https://pkgs.internalpackages.json -
dist/下的 ZIP 文件路径要能被直接 GET 到,例如https://pkgs.internal/dist/vendor/package/1.2.3/abc.zip—— 这个环节最容易被 SELinux 或open_basedir拦截
真正难调的不是命令怎么写,而是 dist URL 背后那一整条 HTTP 链路里,任意一个环节(DNS、证书、Nginx 配置、文件权限、MIME 类型)出错,都会导致 Composer 静默 fallback 到 source,而你只能靠 -v 日志和手动 curl 去逐层确认。

















