不能直接用 composer install 拉取私有包，因 Composer 默认只认 Packagist 官方源，私有包名（如 acme/utils）在 Packagist 不存在，会报错“Could not find package acme/utils”，必须通过 repositories 显式配置私有仓库地址。
为什么不能直接用 composer install 拉取私有包？
因为 Composer 默认只认 Packagist 官方源，私有仓库的包名（比如 acme/utils）在 Packagist 上不存在，composer install 会直接报错：Could not find package acme/utils。必须显式告诉 Composer：“这个包去哪找”。
配置 satis 仓库的两种核心方式
satis 本身不提供 http 服务，它只生成静态 jsON 和 ZIP 包。你需要用 Web 服务器（如 nginx/apache）托管生成的 packages.json，再让 Composer 通过 repositories 指向它。
- 方式一：全局配置（推荐给团队统一镜像）
运行composer config -g repositories.acme '{"type": "composer", "url": "https://mirrors.example.com/satis/"}' - 方式二：项目级配置（适合单个项目临时接入）
在项目composer.json中添加：{ "repositories": [ { "type": "composer", "url": "https://mirrors.example.com/satis/" } ] } - 注意：
url必须以/结尾，否则 Composer 会拼出错误路径（如https://mirrors.example.com/satis/packages.json→ 实际要的是https://mirrors.example.com/satis//packages.json）
satis.json 关键字段怎么写才不出错？
很多团队卡在生成失败或包漏掉，根源常是 require 和 archive 配置不当。
-
name和homepage只是元信息，不影响功能，但建议填真实域名 -
require要写具体包名 + 版本约束，不是通配符：
✅ 正确："acme/utils": "dev-main"
❌ 错误："acme/*": "*"（satis 不支持 glob） - 如果需要下载 ZIP 包（比如离线部署），必须启用
archive："archive": { "directory": "dist", "format": "zip", "skip-dev": true }否则
composer install --prefer-dist会退回到--prefer-source，拉 git 仓库而非 ZIP - 私有 Git 仓库需提前配置好 ssh key 或使用 HTTPS + Token，satis 构建时会 clone，失败则跳过该包且不报错（静默丢包）
为什么 composer update 很慢，甚至超时？
根本原因不是网络，而是 satis 生成的 packages.json 太大，Composer 加载时内存爆满或解析超时。
- 默认 satis 会把所有匹配包的所有版本都写进一个 JSON 文件，100 个包 × 平均 20 个版本 = 2000+ 条目，JSON >5MB
- 解决方案：按组织分拆镜像
为每个部门/业务线单独跑 satis，satis.json中require只写自己关心的包，生成独立packages.json - 加缓存头：Nginx 配置
add_header Cache-Control "public, max-age=3600";，避免每次composer update都重请求 - 禁用 Packagist 回退：在
composer.json加"packagist.org": false，防止 Composer 在私有源查不到时自动切到公网，拖慢速度还暴露内部包名
satis 的坑不在搭建，而在“它不会告诉你哪里没生效”——包没更新？可能是 Git 分支名写错了；composer require 找不到？大概率是 repositories 的 URL 少了末尾斜杠；JSON 体积爆炸？说明你还没做包收敛。这些细节不验证，镜像服务器就只是个摆设。