直接运行 composer create-project satis:satis 会失败，因官方已移除该包且不再维护；须改用 composer create-project composer/satis --stability=stable --keep-vcs，并确保 git 已安装、路径配置正确、PHP 资源充足及 Nginx 配置支持带参静态文件访问。
为什么直接运行 composer create-project satis:satis 会失败
因为官方已将 satis 移出 Packagist 主索引，且不再维护 satis:satis 这个包名。现在必须显式指定 GitHub 仓库地址和稳定版本分支，否则 Composer 会报 Could not find package satis:satis 或解析到废弃的旧镜像。
- 正确命令是：
composer create-project composer/satis --stability=stable --keep-vcs
-
--keep-vcs很关键：保留.git目录，后续才能用git pull更新 Satis 自身（它本身是持续迭代的） - 如果机器没装
git，create-project会静默降级为下载 zip 包，导致后续无法升级——务必先确认git --version
配置 satis.json 时必须避开的三个路径陷阱
Satis 构建过程会把所有包缓存到本地目录，再生成静态 HTML/JSON，路径写错会导致构建成功但客户端拉不到包、或 HTTP 404。
-
output-dir必须是 Web 服务器可直接访问的绝对路径（如/var/www/satis），不能是相对路径或./build -
archive的directory若启用（用于生成 ZIP 包），其路径必须在output-dir内部，否则 Nginx/Apache 无法通过 URL 映射到该目录 - 所有 Git 仓库的
url字段若含内网域名（如git.mycompany.local），确保运行 Satis 的服务器能ping通且 SSH/HTTPS 认证已配置（推荐用 deploy key +ssh-agent）
php bin/satis build 报 file_get_contents(): read of 8192 bytes failed 怎么办
这是 Satis 在并发抓取大量包元数据时，PHP 默认流上下文超时或内存不足导致的中断，不是网络问题，重试大概率失败。
- 加参数限制并发和延长超时：
php bin/satis build satis.json web/ --no-interaction --max-packages=20 --timeout=600
-
--max-packages=20强制分批处理，避免单次加载过多 JSON；--timeout=600把默认 30 秒提到 10 分钟 - 检查
memory_limit：Satis 构建 50+ 包时常驻内存超 512M，建议在命令前临时设高：php -d memory_limit=1G bin/satis build ...
Nginx 配置里漏掉 try_files 会导致 packages.json 404
Satis 生成的是纯静态文件，但 Composer 客户端请求 packages.json 时带了查询参数（如 ?type=package&foo=bar），Nginx 默认不转发带参数的请求到真实文件，而是直接 404。
- 必须在 server 块中加：
location / { try_files $uri $uri/ /index.html; } - 不能只写
try_files $uri =404，否则/packages.json?xxx这类请求全挂掉 - 如果用了子路径（如
https://mirrors.mycompany.com/satis/），root要指向web/目录，且 location 改为location /satis/ { ... }，内部路径对齐
