必须显式禁用packagist.org,即在composer.json的repositories数组末尾添加{"packagist.org": false},否则Composer仍会fallback至官方源;私有源须置顶、type为"composer"、URL末尾带斜杠。

项目 composer.json 必须显式禁用 packagist.org
不加 {"packagist": false},哪怕你写了私有源,Composer 仍会 fallback 到 packagist.org,导致超时、失败或混入公网包。这个开关不是可选配置,是强制要求。
常见错误写法包括:{"type": "composer", "url": "https://satis.internal/", "packagist": false}(合并进同一对象)或把 {"packagist": false} 放在私有源前面。正确顺序必须是:
{
"repositories": [
{ "type": "composer", "url": "https://satis.internal/" },
{ "packagist": false }
]
}
- 私有源必须是独立
{"type": "composer", ...}对象,不能省略type -
url末尾必须带斜杠,否则请求变成https://satis.internal/packages.json→ 404 - 若同时用了 GitLab 私有 VCS 源,它们也得排在
{"packagist": false}前面
私有源注册不能用 composer config repo.packagist
composer config repo.packagist 是专用于替换官方源的命令,对私有仓库完全无效。执行 composer config repo.packagist https://satis.internal/ 不仅不会生效,还可能破坏全局配置。
要往当前项目添加私有源,必须用:
composer config repositories.satis composer https://satis.internal/
它会在 composer.json 的 repositories 数组里插入一个 key 为 satis 的对象。后续 composer require internal/utils 才能命中该源。
使用 circleci/circleci-cli 和 circleci/orb-tools-orb SDK 来组合和验证 CircleCI Orbs。自动化 orb 打包、使用 conventional-changelog 进行语义化版本控制,并发布到 CircleCI Orb Registry。
- 手动编辑
composer.json也可以,但必须确保 JSON 格式合法、缩进一致 - 运行该命令后,建议立刻
composer show --platform验证是否已加载新源 - 不要在 CI 环境中依赖
composer config动态改源——应把完整repositories提交进版本库
Satis 镜像必须生成 packages.json + dist ZIP 包
Satis 不是代理服务,它生成的是静态文件。如果只部署了 packages.json 而没生成 dist/ 下的 ZIP,composer install 会卡在 “Downloading” 阶段,因为找不到可下载的归档文件。
关键配置项必须显式开启:
"archive": {
"directory": "dist",
"format": "zip",
"prefix-url": "https://satis.internal"
}
-
prefix-url必须和项目实际访问的域名一致,不能写成http://localhost或内网 IP - 构建命令必须带输出目录:
php bin/satis build satis.json web/,否则文件不会落地 - 部署时整个
web/目录需被 Web 服务器(Nginx/Apache)直接托管,路径根目录即https://satis.internal/ - 检查
web/packages.json是否可被浏览器直接打开,HTTP 状态码必须是 200
私有包本身要满足 Composer 可识别格式
即使镜像源搭建完成,如果私有包的 composer.json 缺少必要字段,Composer 仍会跳过它或报 Package not found。
最简合规结构至少包含:
{
"name": "company/utils",
"type": "library",
"autoload": {
"psr-4": { "Company\Utils\": "src/" }
}
}
-
name必须符合vendor/package格式,且全小写;不能含下划线或大写字母 -
autoload是硬性要求,没有它,composer install成功但类无法自动加载 - Git 仓库必须打 tag(如
v1.0.0),Satis 默认只抓取带 tag 的稳定版本 - 若使用 GitHub 私有库,需配 Personal Access Token 并写入
auth.json,否则 Satis 构建阶段会因 API 限流失败
packages.json 可访问、dist/ 有 ZIP、项目禁用了 packagist、私有包打了 tag、且 name 格式正确——五者缺一不可。

















