如何为Composer项目配置私有Packagist/Satis仓库？（企业级应用）

为 composer 项目配置私有 Satis 仓库，需在 composer.json 中优先声明 type: “composer” 仓库地址，禁用 packagist.org 回退，配合 auth.json 或环境变量认证，并启用 dist 归档、锁文件提交与元包统一管理，确保安全、稳定、可审计。

为 Composer 项目配置私有 Packagist/Satis 仓库，核心是让 composer install 和 composer require 能安全、稳定地拉取内部包，同时不干扰公共包的正常更新。关键不在“怎么搭”，而在“怎么配得稳、管得住、升级不翻车”。

搭建 Satis 服务（轻量可控的私有仓库）

Satis 是 php 官方推荐的静态私有仓库方案，比完整 Packagist 更适合企业内网或 CI/CD 场景。它不提供 Web 界面交互，但生成的是标准 Composer JSON 元数据，兼容性极好。

• 用 Composer 全局安装 Satis：composer global require composer/satis
• 准备配置文件 satis.json，明确指定哪些 git 仓库纳入索引（支持 httpS/ssh）、是否启用 dist 包、是否镜像部分 packagist.org 包
• 运行构建命令：php ~/.composer/vendor/bin/satis build satis.json web/，输出静态 JSON 和 html 列表到 web/ 目录
• 用 nginx/apache 或简单起一个 PHP 内置服务器（php -S localhost:8000 -t web/）对外提供 packages.json

在项目中声明私有仓库（优先级与安全性）

不是所有项目都需要全部私有包，也不是所有环境都该访问内网仓库。推荐在项目根目录的 composer.json 中用 repositories 声明，并配合 config.platform 和 minimum-stability 控制行为。

• 把私有仓库放在 repositories 数组首位，确保 Composer 优先查它（Composer 按顺序查找，命中即停）
• 使用 type: "composer" + url 指向你的 packages.json 地址（如 https://satis.internal.example.com/packages.json）
• 若仓库需认证，用 auth.json 配置 bearer Token 或 HTTP basic auth，避免密钥硬编码；CI 环境可通过 COMPOSER_AUTH 环境变量注入
• 禁用自动 fallback 到 packagist.org：设 "packagist.org": false 在 repositories 中显式关闭公共源（防意外拉取非审计包）

统一管理私有包版本与依赖策略

企业级场景下，不能靠开发者手动 require vendor/private-package，而应通过“元包（metapackage）”或“锁文件策略”收口。

• 创建一个内部 company/base-composer-config 包，含标准 require-dev 工具链和 conflict 规则，供所有项目 require
• 在 Satis 配置中启用 "archive": {"Directory": "dist", "format": "zip", "skip-dev": true}，强制生成可缓存、可校验的 dist 包，避免每次 clone 源码
• CI 流水线中，在构建前执行 composer update --lock 并提交 composer.lock，确保私有包版本锁定且可追溯
• 对敏感包（如加密 SDK、内部 API 客户端），在 composer.json 中加 "abandoned": true 或 "private": true 标记，防止误发布

权限隔离与审计落地（合规刚需）

私有仓库不是“开了就能用”，必须满足最小权限、操作留痕、变更受控。

• Satis 构建服务器只读取 Git 仓库的 tag/branch，不执行代码；Git 仓库本身应设置 protected branches + PR 强制检查（如 PHP-CS-Fixer、PHPStan）
• 所有私有包的 composer.json 必须含 "license" 字段（如 "proprietary"），并统一在 Satis 配置中开启 "require-all-packages": true 强制校验
• 定期用 composer show --outdated 扫描项目中私有包的更新情况，结合内部通知机制推动升级
• 记录每次 satis build 的 Git commit hash 和时间戳，写入 web/build-info.json，便于审计回溯

基本上就这些。不复杂但容易忽略的是：仓库地址要稳定（别用 localhost 或临时域名）、认证方式要统一（别混用 token 和密码）、锁文件要进 Git（别让 CI 每次重算依赖）。企业级不是堆功能，而是让每一次 composer install 都可预期、可验证、可兜底。