本速查表涵蓋 Nginx 設定產生器的精確輸入、驗證規則、產生的伺服器區塊指令，以及決定此工具何時是小型靜態來源正確選擇的各項限制。產生器會在瀏覽器中本地組裝一個窄化的 HTTP 伺服器區塊,用於單一網域在 IPv4 與 IPv6 的 80 埠,搭配固定的 server_name、絕對 POSIX 文件根目錄,以及可選的 SPA 後援、資產快取與 gzip,整個過程都在本地瀏覽器中完成,不會將設定資料傳送到伺服器。當你需要快速回想哪些指令會被輸出、哪些值會被拒絕,以及工具刻意省略哪些項目時,可將其作為快速參考,如此你便能依據已審閱的文件完成伺服器設定的其餘部分,而非憑空猜測。底下的每一行都可對應回產生器的合約,或對應回 Nginx 核心與 gzip 模組文件,因此這份參考能誠實反映哪些是可設定的、哪些必須在工具之外另行新增。
本速查表涵蓋哪些內容
本參考文件的範圍僅限於產生器實際支援的靜態網站路徑:一個網域、一個文件根目錄、一個位於 80 埠的伺服器區塊,以及一組小型固定的快取與壓縮選項。這是一份給已知道 Nginx 伺服器區塊長什麼樣、希望快速確認工具接受哪些值、輸出哪些指令,以及不會推測哪些行為的讀者使用的快速查詢表。它並非設定 Nginx 的一般教學,也無法取代在部署需要產生器未輸出之指令時,閱讀 Nginx 核心模組文件 的必要性。
有兩件事讓本速查表與一般性的 Nginx 參考不同。首先,產生器的合約刻意限制輸入,因此速查表會在可接受的值旁列出拒絕規則。其次,工具刻意省略了整個類別,例如 TLS、PHP-FastCGI、反向代理與安全性標頭,因此速查表會明確列出這些省略項目,以避免讀者誤以為輸出內容已是一個完整的正式環境基準設定。
輸入與驗證規則
每個輸入欄位都有定義明確的型別與拒絕規則。在產生區塊之前,請將下表視為表單中可輸入與不可輸入內容的權威性檢查清單。
| 輸入 | 可接受型別 | 驗證規則 |
|---|---|---|
| 網域 (server_name) | 純主機名稱字串 | 僅接受一個精確名稱;不可使用萬用字元、規則運算式、通訊協定前置,亦不接受替代的 www 主機。 |
| 文件根目錄 | 絕對 POSIX 路徑 | 必須以 / 開頭,並使用有界的安全路徑字元;分號、大括號、變數、空白字元及類似 shell 的語法都會被拒絕,以免使用者輸入產生額外的指令。 |
| 快取持續時間 | 整數天數 | 範圍 1 至 365(含);超出此範圍的值會被拒絕。 |
| 後援模式 | 靜態 404 或 SPA 後援 | 必須刻意選擇;切換會改變最終的 try_files 引數。 |
| gzip | 切換開關 | 可選;啟用時,會輸出標準 gzip 篩選器、Vary: Accept-Encoding,以及固定的 gzip_types 清單。 |
路徑仍必須在目標伺服器上存在,並具備正確的擁有權與讀取權限;瀏覽器無法檢查這些事實,因此本工具不會宣稱該根目錄可連線。
如何逐步執行產生器
請依下列具體步驟依序執行 Nginx 設定產生器,使輸出能清楚地對應至已審閱的部署:
- 輸入一個精確的網域、一個安全的絕對文件根目錄、以天數表示的快取持續時間,以及在靜態 404 與 SPA 後援之間的刻意選擇;除非資產組合確實需要,否則請將 gzip 維持關閉。
- 產生區塊後,逐行閱讀每個輸出的指令,在儲存檔案前,將每一行與已安裝的 Nginx 模組、部署的 include 鏈,以及所選的快取策略進行比對。
- 備份目前使用中的設定,並記錄目前的 include 鏈,以便變更可還原,接著將已審閱的片段置於正確的脈絡中,例如啟用站台中的伺服器區塊片段。
- 對完整設定執行 nginx -t;通過語法測試僅能證明指令結構與參照正確,無法證明其他事項,因此失敗時請勿重新載入,且絕對不可略過此測試。
- 透過平台支援的程序重新載入,而不是突然停止服務,並保持一個復原 shell 開啟,接著請求靜態檔案、快取資產,以及所選後援行為的代表路徑。
伺服器區塊指令參考
產生器會在一個 HTTP 伺服器區塊內輸出一組固定的指令。下表為輸出內容的完整清單;任何你需要、但未列於此清單中的指令,都必須依據已審閱的文件另行新增。
| 指令 | 在產生區塊中的用途 |
|---|---|
| listen | IPv4 與 IPv6 的 80 埠,這是產生器唯一會輸出的 listen 形式。 |
| server_name | 取自已驗證網域欄位的一個精確主機名稱;不接受替代的 www 或萬用字元。 |
| root | 用於提供靜態檔案服務的已驗證絕對文件根目錄。 |
| index | 請求目錄時所使用的預設 index 檔案。 |
| location / | try_files 鏈,包含請求的 URI、目錄形式,以及最終的後援,後者為靜態 404 或 SPA 模式下的 /index.html。 |
| location ~* 用於資產 | 對固定副檔名清單(涵蓋 CSS、JavaScript、常見影像格式、圖示檔案與 WOFF2 字型)進行不區分大小寫的比對。 |
| expires | 以天數表示的所選快取持續時間,套用於資產 location 內部。 |
| Cache-Control | 在資產 location 中新增 public,以便中介快取能夠快取回應。 |
| gzip、gzip_types、gzip_vary | 標準篩選器、固定型別清單與 Vary: Accept-Encoding,僅在 gzip 切換開關開啟時才會輸出。 |
區塊邊界由工具的測試所斷言,因此具有相同 listen 與 server_name 的重複伺服器區塊無法通過測試,這能讓輸出在進入既有的 include 鏈時保持可預測性。
靜態後援與 SPA 後援
後援選擇僅會改變 location / 中 try_files 鏈的最後一個引數,但其運作後果卻很重大,且很容易搞反。對於一般的靜態網站,該鏈會以一個真實的 404 後援作結,因此缺少的資源會回傳真正的 not-found 回應,中斷的 URL 在錯誤監控中會保持可見。對於單頁應用程式,該鏈則會以 /index.html 作結,因此用戶端路由可在未知的應用程式路徑接手,並提供應用程式外殼。
請勿為一般的內容網站啟用 SPA 後援:對缺少的資源回傳狀態碼為 200 的首頁外殼,會隱藏中斷的 URL、削弱錯誤語意,並可能使爬蟲與正常運行時間檢查產生混淆。反之,亦請勿在依賴 history-based 路由的 SPA 上保留靜態 404,因為訪客與爬蟲將會對每一個用戶端路由器原本可處理的深層連結,看到一個硬性的 404。這個決定必須是刻意的,並且必須與應用程式在目標伺服器上的實際行為相符。
快取持續時間與 gzip 設定
資產 location 內部的 expires 指令會使用所選的 1 至 365 天持續時間,並新增 Cache-Control public,以便中介能夠儲存回應。請挑選在不讓已加入版本或指紋資訊的資產於部署後無法安全重新驗證的前提下,所能使用的最長持續時間;否則訪客將在發版後持續取得過時檔案,而強制重新整理將成為常態。
可選的 gzip 會啟用標準篩選器、新增 Vary: Accept-Encoding,並在 gzip_types 中列出 CSS、JavaScript、JSON 與 SVG。HTML 由 Nginx 的 gzip 行為處理,無需列於型別清單中,且工具刻意不會新增其他文字型別或預先壓縮的變體。壓縮可能對反映於壓縮回應中的機密資料產生側通道疑慮,而預先壓縮的資產需要不同的設定,因此請依據實際網站與安全性情境進行評估,而非假設某個切換開關在任何情況下都是安全的。
產生器刻意省略的內容
輸出內容省略了一長串其他 Nginx 工具常宣稱能產生的功能,這些省略屬於合約的一部分,並非疏漏。TLS 被排除,這是因為憑證路徑、續期工具、支援的通訊協定、重新導向、代理或 CDN 拓撲,以及 HSTS 政策皆仰賴部署特定的證據;憑空捏造憑證位置將會產生危險的虛假信心。PHP、FastCGI、反向代理、WebSocket、上傳、驗證、速率限制、自訂錯誤頁面、MIME include 路徑、日誌記錄與安全性標頭同樣皆未包含。其結果是一個靜態網站片段,並非適用於所有應用程式的正式環境基準設定,因此請僅在區塊產生之後,依據實際架構與官方模組文件,新增必要的指令。
僅在問題真正屬於小型靜態來源時,才使用本產生器。對於代管主機、容器、Kubernetes ingress 或 CDN,正確的設定介面可能位於別處,而最易於維護的結果,通常會是與當前部署證據相符的最小且已審閱的設定。
在重新載入前測試產生的區塊
通過 nginx -t 僅能證明指令在語法上有效,以及所參考的檔案與 include 能正確解析,但無法確認檔案擁有權、讀取權限、DNS 解析、應用程式路由、憑證行為或快取回應標頭。在語法測試通過後,請對一個 HTML 頁面、一個快取資產、一個應觸發所選後援的缺失 URL,以及 SPA 模式下 SPA 路由器會攔截的任何路徑,請求其代表路徑。將回應狀態、內容類型、快取標頭與 gzip 標頭與產生器所述行為進行比對,並檢查錯誤記錄中是否有權限或路徑不符的情形,而這些是語法測試無法察覺的。
請透過平台支援的程序重新載入,而不是突然停止 Nginx,保持一個復原 shell 開啟,若重新載入後請求失敗,請立即還原備份。永久性的快取與路由錯誤即使在 Nginx 仍正常運作時,仍會影響訪客,因此唯一安全的順序為:備份、置入脈絡、語法測試、代表請求,接著再重新載入。至於將本參考與檔案權限及重新載入步驟搭配的更廣泛部署流程,靜態網站 Nginx 設定指南 會逐步說明相關程序。gzip 模組參考 仍是本產生器未公開之任何壓縮行為的真相來源。
若你正在權衡選項,結構化資料標記產生器速查表:欄位與規則 對此有詳細說明。