Configuration zh

配置参考

SPACK 面向用户的配置文档以 GitHub Wiki 为权威入口。运行时默认值、命令行参数、环境变量和配置文件需要在同一个发布线内遵守这里描述的契约。

API 版本

SPACK 运行时配置使用显式 API 版本：

apiVersion: spack.io/v1alpha1
kind: RuntimeConfig

这个版本字段用于后续字段重命名、默认值调整和弃用迁移。

最小运行时配置

直接服务前端 dist/ 目录：

apiVersion: spack.io/v1alpha1
kind: RuntimeConfig

assets:
  root: /app
  path: /
  entry: index.html
  fallback:
    on: not_found
    target: index.html

服务编译器生成的 .spack 包：

apiVersion: spack.io/v1alpha1
kind: RuntimeConfig

assets:
  root: /app/app.spack
  path: /
  entry: index.html
  fallback:
    on: not_found
    target: index.html

配置优先级

配置来源按以下顺序合并，越靠后的优先级越高：

1. 内置默认值
2. .env 和 .env.local
3. --config 传入的配置文件
4. 环境变量
5. 命令行参数

命令行参数使用配置路径形式，例如 --compression.mode=warmup。

编译器优化配置

压缩和图片优化属于编译器职责。运行时仍然可以直接服务普通源目录；AOT 包则可以包含预计算的压缩变体、图片变体、资源提示和索引元数据。

图片编译路径使用 libvips。生成图片变体需要 CGO、libvips 运行时库，以及可通过 pkg-config 发现的 libvips 开发元数据。

image:
  enable: true
  widths: "640,1280,1920"
  formats: ""
  jpeg_quality: 78
  max_source_bytes: 10485760
  max_source_pixels: 25000000
  max_width: 10000
  max_height: 10000
  max_output_variants: 12
  max_concurrent_sources: 2
  max_memory_bytes: 134217728
  min_saving_ratio: 0.05
  min_saving_bytes: 1024

图片生成按源资源批处理：SPACK 对同一张源图只解码一次，构建宽度金字塔，然后从这个批次中编码请求的宽度和格式变体。不满足收益阈值的变体不会写入 bundle 或产物输出。

max_memory_bytes 是图片引擎实例共享的全局预估解码内存预算。每个批次会在完整解码前预估源图和金字塔内存，并等待预算容量；如果单个批次超过预算，则跳过该批次。

旧版本资源恢复

frontend.stale_asset_recovery.enable 默认是 true。如果希望资源缺失时保持 404，可以关闭：

frontend:
  stale_asset_recovery:
    enable: false

发布新版本后，旧 HTML 页面可能继续请求已被删除的带指纹 JavaScript 分块，例如 assets/chunk.abc123def456.js。如果运行时无法解析这个请求，旧版本资源恢复会返回一段 JavaScript，HTTP 状态为 200，并设置 Content-Type: application/javascript 和 Cache-Control: no-store。脚本调用 location.reload()，尝试重新获取当前页面。该开关同时适用于直接目录和 AOT 包交付。

这只是带指纹 .js 请求失败时的兜底，不是浏览器缓存版本检测。CSS、图片和不带指纹的 JavaScript 不会触发它。若请求直接命中浏览器缓存、Service Worker 或 CDN，就不会到达这段运行时逻辑。若上游缓存没有重新验证 HTML，刷新后仍可能得到旧页面。需要保持旧会话不中断时，发布期间继续提供旧分块更可靠。

部署检查

不启动服务，只校验配置文件：

spack config validate --file spack.yaml

输出合并默认值、配置文件、环境变量和命令行参数后的最终配置：

spack config print-effective --file spack.yaml --redact

--redact 会隐藏 assets.root、compression.cache_dir 和 logger.file.path 这类本地文件系统路径。