2026-06-1614 分鐘閱讀

部署出問題前，先預覽 .env、YAML、TOML 和 Nginx 設定

一篇面向部署前檢查的設定預覽教程，覆盖 .env 差异、YAML 路径、TOML 結構、Nginx location 匹配和生产事故常见錯誤。

設定問題預覽成本低，线上代价高

設定問題在 code review 里看起来很小，但上線后代价很高。少一个環境變數、镜像 tag 还是 latest、TOML 預設值不对、Nginx location 匹配错，都可能让發布翻车。

所以設定类博客不能只说“这是一个工具”，而要展示部署前怎么把这些文件串起来檢查。

部署前設定預覽 — 实用的部署前檢查应该把 .env 差异、YAML 路径、TOML 結構和 Nginx 路由匹配放在一起。

Demo 1：比對 .env 和 .env.example

最直接的收益是檢查运行環境變數和 example 是否一致。缺少 key 很明显，但空值和重複 key 同样危险。

这个 demo 能发现常见上線問題：example 里写了變數，但真實環境没設定。

dotenv

DATABASE_URL=postgres://local
NEXT_PUBLIC_SITE_URL=https://example.com
STRIPE_SECRET_KEY=
---
DATABASE_URL=
NEXT_PUBLIC_SITE_URL=
STRIPE_SECRET_KEY=
WEBHOOK_SECRET=

这里应该提示 WEBHOOK_SECRET 缺少，并提示 STRIPE_SECRET_KEY 为空。

Demo 2：只檢查真正会部署的 YAML 值

Kubernetes、Helm、GitHub Actions 文件通常很长。YAML Path 預覽适合问一个具体問題：这次部署到底用哪个 image、branch、CPU limit 或 secret name。

当 review 关注一个生产值时，这比展示完整 YAML 树更有效。

yaml

spec.template.spec.containers[0].image
---
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: api
          image: example/api:latest

如果生产还在用 latest，应该在發布前明确标出来。

Demo 3：檢查 TOML section 和預設值

TOML 常见于 pyproject、Cargo、应用設定和内部工具。它可读性不错，但生产預設值仍然可能不合适。

結構預覽可以让 reviewer 快速扫 section、key 和 value，不需要先理解完整应用。

toml

[server]
port = 3000
workers = 1

[features]
search = true
new_checkout = false

文章里要解释哪些 TOML 值是安全預設值，哪些需要按環境复核。

Demo 4：测试 Nginx location 匹配

Nginx 路由 bug 容易漏，因为 exact、prefix、^~、regex 的优先级不同。設定看起来对，但实际可能命中另一个 block。

部署 rewrite 或 proxy 规则前，应该把目标 URI 和相关 location block 单独拿出来預覽。

nginx

URI: /api/users/42
---
location = /health { return 200; }
location ^~ /api/ { proxy_pass http://api; }
location ~ \.(js|css)$ { root /assets; }
location / { try_files $uri /index.html; }

预期应命中 ^~ /api/，而不是 fallback location。

这份 checklist 能发现什么

secret 在 example 里有，但真實環境没有；部署镜像仍然使用 latest；TOML worker 数本地够用但生产不够；regex route 抢走 prefix route 的流量；缓存回應头让客户端一直保留旧 bundle。

这些具体錯誤会让文章像發布经验，而不是普通工具介绍。

什么时候不能只依赖預覽

預覽不能替代 staging 部署、secret 扫描或真實健康檢查。它的价值是提前发现明显不一致。

最终發布仍然要看真實環境變數、已部署 manifest、Nginx reload 校验和应用日志。