Nginx 設定產生器範例：您實際獲得的內容

一個可運作的 Nginx 設定產生器範例會產生一個可審核的 HTTP server 區塊，包含精確的 listen 設定、一個 server_name、一個絕對 document root、try_files fallback、有界限的資產快取以及選用的 gzip 指令，讓你在放入實際運作的設定之前，依部署的 Nginx 版本進行檢視。這個區塊刻意保持精簡：它涵蓋的是一個小型靜態來源，而非完整的正式環境基準。輸入會經過驗證，使分號、大括號與類似 shell 的語法無法注入額外的指令，而產生的片段應該逐行閱讀，而不是盲目貼上。每個指令都對應 Nginx 核心與 gzip 模組中已記載的行為，限制也都明確標示。TLS、FastCGI、proxy、上傳、驗證、速率限制與安全標頭會刻意略過，因為它們取決於瀏覽器看不到的部署證據。將這個範例視為可審閱的片段，而非已完成的正式環境檔案，才是它有用的原因。

這個工具的合約很簡單。它完全在瀏覽器中執行，接受一個精確的網域、一個絕對 document root、一個介於 1 到 365 天的整數快取時間、一個 SPA fallback 開關，以及一個 gzip 開關，然後組裝出一個固定的 HTTP 區塊。輸出會保留在本機；不會上傳任何內容。由於每個輸入都經過驗證，每個指令都由已記載的 fixture 產生，因此你所複製的範例區塊是可重現的。以相同的值執行工具會產生相同的文字，這正是它可審核而非憑空猜測的原因，也說明了為什麼當你逐行檢視每個指令時，結果會自然地與 Nginx 核心模組說明文件相互搭配。

nginx config generator example — Nginx 設定產生器範例：你實際會得到的內容

產生器並列涵蓋的兩種情境

產生器接受一組少量的輸入，並依兩種形式之一產生對應的區塊：一個帶有明確 404 的普通靜態網站，或是一個未知路徑應 fallback 至 index.html 的單頁應用程式。下表顯示在這兩種情境中，輸入與最終產生的 try_files 指令有何不同。

欄位	靜態網站	單頁應用程式
網域 (server_name)	一個精確的 host	一個精確的 host
Document root	絕對 POSIX 路徑	絕對 POSIX 路徑
快取時間	1 到 365 天	1 到 365 天
SPA fallback 開關	關閉	開啟
最終 try_files 引數	=404	/index.html
listen 設定	80; 與 [::]:80	80; 與 [::]:80
資產 location 副檔名	CSS、JS、圖片、icons、WOFF2	CSS、JS、圖片、icons、WOFF2
選用的 gzip 類型	CSS、JS、JSON、SVG	CSS、JS、JSON、SVG

這兩種形式共用相同的 listen 設定（IPv4 與 IPv6 的 port 80）、相同的精確 server_name 規則、相同的資產 location，以及相同的選用 gzip 區段。唯一行為上的差異在於最終的 try_files 引數，而產生器只允許你刻意切換，而不是依網域去推測。在一般的內容網站上啟用 SPA fallback 是已知的陷阱：對缺失的資源回傳狀態 200 的 home shell，可能會掩蓋損壞的 URL 並破壞錯誤語意，因此這個開關雖然存在，但並不是預設行為。

產生器會接受與不會接受的輸入

表單會拒絕看起來像設定而非值的輸入。帶有 https:// 或 http:// 等 scheme 的網域會被拒絕。document root 若包含分號、大括號、空白、變數或任何類似 shell 的語法，也會被拒絕。快取時間若超出 1 到 365 天的合約範圍，一樣會被拒絕。路徑驗證不會檢查該目錄是否存在於目標伺服器上、擁有者是否符合 Nginx worker 使用者，或該路徑是否可讀；這些瀏覽器無法檢視的資訊會留給部署階段處理。產生器也拒絕加入萬用字元、替代的 www host 或 regex server_name，因為每一個這類選擇都會影響虛擬主機路由與憑證涵蓋範圍。如果有多個名稱應該提供服務或重新導向，則必須在周圍的設定中明確設計，而不是從單一輸入欄位去推測。

資產 location 涵蓋一組固定的清單：CSS、JavaScript、常見圖片、icons 與 WOFF2 字型。expires 指令會套用所選的時間，並加上 Cache-Control public。如果你選擇較長的快取時間，請為靜態資產加入版本編號或 fingerprint，以免部署後使用者持續拿到舊檔。產生器並不會改寫你的檔名。選用的 gzip 區段會啟用標準的 filter，加上 Vary: Accept-Encoding，並列出 CSS、JavaScript、JSON 與 SVG；HTML 由 Nginx 預設的 gzip 行為處理，不需要列入 gzip_types，這與 Nginx gzip 模組說明文件中描述的行為一致。壓縮可能會對反映在壓縮回應中的機密資料產生側通道疑慮，而預先壓縮的資產需要不同的設定，因此這個開關會被明確記載，而不是預設啟用。

逐步檢視產生的範例

以下是從輸入到可複製區塊的具體路徑。每一步都是刻意的動作，伺服器端不會自動處理任何事。以這種方式閱讀範例，能讓輸出保持可審閱，而非難以理解。

輸入一個精確的網域。輸入單一 host，例如 www.example.com。scheme、路徑、萬用字元與 regex 字元會在此步驟被拒絕。相同的網域會原樣出現在產生的 server_name 行中；不會自動加入替代或 www 別名。
輸入絕對 document root。使用完整的 POSIX 路徑，例如 /var/www/example.com/html。產生器只接受有限的、安全的路徑字元；分號、大括號、變數、空白與類似 shell 的語法會導致拒絕。該路徑仍必須存在於目標伺服器上，且擁有正確的擁有者與讀取權限，瀏覽器無法驗證這些事實。
選擇快取時間。輸入介於 1 到 365 之間的整數。該值會成為資產 location 中的 expires 引數，並搭配 Cache-Control public。如果你在沒有檔名或 query-string 版本化的情況下提供長效資產，請選擇較短的時間，以避免部署後出現舊檔。
選擇靜態 404 或 SPA fallback。一般內容網站請將 SPA fallback 關閉，使缺失路徑回傳 =404。只有在用戶端路由需要接收未知應用程式路徑時才開啟；此情況下，最終的 try_files 引數會變成 /index.html。
視需要切換 gzip。當你希望壓縮 CSS、JavaScript、JSON 與 SVG 回應並加上 Vary: Accept-Encoding 標頭時啟用。當回應可能包含壓縮會洩漏的機密資料，或資產已預先壓縮時，請關閉。
產生並檢視區塊。輸出是一個 HTTP server 區塊，於 IPv4 與 IPv6 的 port 80 上監聽，包含一個精確的 server_name、所選的 root、location / 的 try_files、一個不分大小寫的資產 location，以及選用的 gzip 行。請在複製前逐行閱讀。
將片段放入適當的設定脈絡中。儲存目前運作的設定並記錄 include 鏈。將檢視過的檔案放入 nginx.conf 或 sites-enabled include 中的正確位置。不要為同一個名稱重複 server 區塊；產生器的測試會斷言精確的區塊邊界。
對完整設定執行 nginx -t。通過語法測試只能證明指令與引用解析無誤，僅此而已。如果失敗，請修正設定後重新測試；不要直接 reload。
測試具代表性的請求。測試首頁路徑、已知資產、已知缺失路徑，以及（若啟用 SPA fallback）未知的應用程式路徑。確認狀態碼、快取標頭、gzip 行為，以及是否提供正確的檔案。nginx -t 無法證明檔案權限、DNS、應用程式路由或憑證行為，因此這一步是必要的。
使用 reload 而非 stop。當平台程序支援 graceful reload 時，請使用它。保持一個復原 shell 開啟。如果 reload 後請求失敗，請還原備份並檢查錯誤記錄，再進行下一輪。

對於想看到實際產生文字的讀者，Nginx 設定產生器完全在瀏覽器中執行，並依上述輸入產生完全相同的區塊。Nginx 設定產生器速查表將此範例與每行所引用的精確指令與限制搭配在一起，在產生第一個區塊之後，是一篇有用的延伸閱讀。

將範例與手寫 server 區塊進行比較

閱讀產生的範例時，一個有用的方式是將它與為相同目的手寫的 server 區塊進行對比。兩者最終都是監聽 port 80 的 HTTP server，都帶有單一 server_name 與 document root，且在謹慎設定下都能正確提供靜態檔案。差異體現在範圍與防護機制上，而不是任何單一行。

手寫區塊可以在同一處加入萬用字元、regex server name、替代的 www host、redirect 與 rewrite，因為作者心中有完整的部署考量。產生的範例則刻意拒絕這些選擇，因為它們會影響虛擬主機路由與憑證涵蓋範圍，也因為瀏覽器無法從單一輸入欄位推測多個名稱的擁有權。手寫區塊可以包含 TLS、FastCGI、proxy 與安全標頭；產生的範例則全部省略，理由是這些指令依賴憑證路徑、後端位址與標頭政策，而這些都是工具無法看見的。手寫區塊會受作者習慣與周圍設定的影響而塑形；產生的範例則受限於一組固定的已記載 fixture，因此相同的輸入可以產生可重現的輸出。

實際上的結論是：產生的範例是一個較小、更可預測的起點，而手寫區塊則是一個較大、更具脈絡意識的成品。兩者並不能互相取代：產生器產生的是一個可審閱、可放入實際設定的片段；而當靜態網站的假設不再成立時，則適合採用手寫區塊。

What the Example Deliberately Leaves Out

The example is a static-site fragment, not a production baseline for every application. TLS is intentionally excluded: correct HTTPS depends on certificate paths, renewal tooling, supported protocols, redirects, proxy or CDN topology and HSTS policy, and inventing certificate locations would produce dangerous false confidence. HTTPS has to be configured through the hosting platform or a reviewed server procedure, then the HTTP-to-HTTPS behavior tested separately. The output also omits PHP and FastCGI, reverse proxying, WebSockets, uploads, authentication, rate limits, custom error pages, MIME include paths, logging and security headers. Each of those belongs in a separate, evidence-led decision against the actual architecture and the official Nginx module documentation.

The most maintainable result is the smallest reviewed config that matches current deployment evidence. If traffic lands on managed hosting, containers, Kubernetes ingress or a CDN, the correct configuration surface may be elsewhere, and a static-site generator block is the right starting point only when the problem really is a small static origin. When you do deploy the example, treat it as a reviewable fragment: back up the active configuration, place the file in context, run nginx -t, test representative requests and reload rather than stop. Permanent cache and routing mistakes can affect visitors even while Nginx remains online, so the testing sequence exists to surface them before real traffic does.