Satis私有仓库易失败因它非镜像站而是静态生成器，需Nginx/Apache托管、URL末尾加/、require-all或显式require、禁用packagist.org且清缓存。
为什么直接用 Satis 搭建私有仓库容易失败
因为 Satis 本质不是“镜像站”，而是静态包生成器——它不提供实时 HTTP 服务，也不代理 packagist.org 请求。很多人误以为装完就能当 Composer 镜像用，结果 composer install 报 Could not find package xxx 或 404，其实是没配好 Web 服务器或 JSON 路径不对。
真正能跑起来的关键是：Satis 生成的 packages.json 必须能被 Composer 通过 HTTP 正确读取，且所有包 ZIP 文件路径要可访问。
- 必须用 Nginx/Apache 托管生成目录（不能只用 PHP 内置服务器）
-
repositories里填的 URL 必须以/结尾，否则 Composer 会拼错packages.json路径 - Satis 不支持按需构建，每次新增包都要手动运行
satis build
如何正确配置 satis.json 并生成可用仓库
最简可用的 satis.json 要明确指定输出路径、仓库源和 require 规则。别照抄文档里的复杂示例，先跑通再扩展。
示例配置（保存为 satis.json）：
立即学习“PHP免费学习笔记（深入）”；
{
"name": "my-private-packages",
"homepage": "https://pkg.example.com",
"repositories": [
{ "type": "vcs", "url": "https://git.example.com/internal/lib-a" },
{ "type": "vcs", "url": "https://git.example.com/internal/lib-b" }
],
"require-all": true,
"output-dir": "/var/www/pkg.example.com"
}
-
output-dir必须是 Web 服务器可读的绝对路径，且该目录要有写权限 -
require-all: true表示拉取所有 tagged 版本；如只需特定版本，改用"require": { "vendor/lib-a": "dev-main" } - Git 仓库必须有符合 Composer 规范的
composer.json，且至少打过一个 tag（如v1.0.0），否则 Satis 会跳过
Web 服务器怎么配才能让 Composer 正常访问
Nginx 是最稳妥的选择。关键点不是反向代理，而是让 packages.json 和 ZIP 文件直出，且不触发 PHP 解析。
典型 Nginx 配置片段（对应 output-dir）：
location / {
try_files $uri $uri/ =404;
add_header Access-Control-Allow-Origin *;
}
location ~ \.json$ {
add_header Content-Type application/json;
}
- 必须去掉
index.php或其他 PHP 处理逻辑，否则访问packages.json会 500 - 如果 ZIP 包下载时中断或校验失败，检查
client_max_body_size和gzip off（Satis 生成的 ZIP 已压缩） - 浏览器直接打开
https://pkg.example.com/packages.json能看到 JSON 内容，才算成功
客户端 composer.json 怎么写才不报错
不是加个 repositories 就完事。Composer 默认只查 packagist.org，私有仓库必须显式启用，并注意包名冲突。
项目级 composer.json 示例：
{
"repositories": [
{
"type": "composer",
"url": "https://pkg.example.com/"
},
{ "packagist.org": false }
],
"require": {
"internal/lib-a": "^1.2"
}
}
-
"url"后面的斜杠/不能少，否则 Composer 会请求https://pkg.example.compackages.json（404） -
{ "packagist.org": false }必须显式禁用默认源，否则 Composer 仍会去公网查重名包，导致超时或混用版本 - 第一次使用前清掉缓存：
composer clear-cache，否则可能读到旧的 metadata
复杂点在于：Satis 不处理依赖传递自动解析，所有间接依赖也得在 satis.json 的 repositories 里列全，否则 build 出来的 packages.json 里就没有它们。这点容易被忽略，直到 composer install 卡在某个未声明的依赖上。
