產生一個可運作的 Nginx 設定檔,代表要輸出一個 HTTP server 區塊,其指令必須符合你已安裝的模組、磁碟上的 document root,以及你實際服務的請求模式。Nginx Config Generator 會建立一個範圍明確的 HTTP server 區塊,在 IPv4 與 IPv6 的 80 埠上接聽、設定一組精確的 server_name、定義絕對路徑的 document root、宣告靜態 404 或 SPA 的 try_files 備援、套用範圍明確的資產快取 duration,並可選擇性地在已記錄的檔案類型清單上啟用 gzip。輸出內容都保留在你的瀏覽器內,輸入在組裝前會根據注入式語法進行驗證,而結果刻意只是一個片段,讓你在更大的 Nginx 安裝環境中檢視,而非完整的正式環境基準。TLS、PHP、反向代理、驗證、速率限制、自訂錯誤、記錄與安全標頭都被刻意排除,因為這些都仰賴瀏器無法檢視的部署證據。一開始就理解這些界線,正是設定檔能否值得信賴,還是在真實流量下悄悄失敗的差別所在。
產生器輸出的內容,以及為何範圍刻意縮窄
產生器會組裝單一 HTTP server 區塊,指令來自核心 Nginx 模組。該區塊會在 IPv4 與 IPv6 的 80 埠上接聽、設定一組與你輸入網域完全相符的精確 server_name、將 root 指向你提供的絕對 POSIX 路徑、宣告 index,並透過 try_files 鏈處理請求,結尾會是明確的 404 備援,或是 SPA 的 /index.html 備援。另一個獨立、不分大小寫的 asset location,會比對一組小型固定的副檔名清單,涵蓋 CSS、JavaScript、常見影像、圖示以及 WOFF2 字型,並使用你選定的 1 至 365 天 duration,搭配 Cache-Control public 套用 expires 指令。
這個區塊刻意保持範圍縮窄。輸出會排除 HTTPS、PHP、FastCGI、反向代理、WebSocket、上傳、驗證、速率限制、自訂錯誤、MIME include 路徑、記錄與安全標頭。新增上述任何一項都需要覽器無法檢視的部署特定證據,因此產生器也不會自行臆造憑證路徑、續期工具、重新導向政策、HSTS 行為或代理拓樸。從瀏覽器送出的設定是一個靜態網站片段,應逐行檢視,而非開箱即用的正式環境基準。這項區分很重要:nginx -t 通過並不代表網站安全,只能證明指令語法可以解析。
你可以在 Nginx Config Generator 說明文件中檢視完整的指令集;每個區塊都會比對八組官方說明文件的 fixture,確保 listen 形式、精確的 server_name、root、靜態與 SPA 的 try_files 備援、asset 過期設定,以及 gzip 類型都與模組參考文件一致。
產生器在組裝前會驗證的輸入
產生區塊的輸入分為三類,每類在組裝前都會進行檢查。首先,網域欄位只接受一組精確的主機名稱,並會拒絕通訊協定前置詞、埠號、路徑與萬用字元。新增萬用字元、備用 www 主機或正規表示式,會改變虛擬主機路由與憑證涵蓋範圍,因此這些選擇會延後到你可控的步驟,而不是由系統猜測。其次,document root 必須是由範圍明確的安全路徑字元所組成的絕對 POSIX 路徑。分號、大括號、變數、空白字元以及類 shell 語法都會被拒絕,因此你輸入的路徑無法被誘導成額外的指令。該路徑仍必須在目標伺服器上存在,並具備正確的擁有權與讀取權限;覽器無法驗證這些事實。第三,快取 duration 必須是介於 1 至 365 天之間的整數。超出此範圍的值會驗證失敗,並不會產生任何區塊。
兩項二元選擇決定了請求的處理方式。備援選擇器決定 location / 是以 try_files ... =404 收尾(適用於一般內容),還是以 /index.html 收尾(適用於單頁應用程式)。在一般內容網站啟用 SPA 備援,會讓找不到的資源以狀態 200 回傳首頁外殼,這會隱藏損壞的 URL 並破壞錯誤語意,因此這項選擇必須符合應用程式模型。gzip 選擇器會啟用標準的 gzip 篩選器、新增 Vary: Accept-Encoding,並在 gzip_types 中列出 CSS、JavaScript、JSON 與 SVG;HTML 由 Nginx 預設行為處理,不需另外列出。這兩項選擇都是刻意設計,而非預設,因為兩者都會對快取、錯誤回報與壓縮側通道產生實質影響。
如何使用 Nginx Config Generator 取得 Nginx 設定
- 在瀏覽器中開啟 Nginx Config Generator,輸入一組精確的網域、目標伺服器上 document root 的絕對 POSIX 路徑,以及介於 1 至 365 天之間的整數快取 duration。
- 選擇備援模式——一般內容網站使用靜態 404,只有當用戶端路由需要接收未知的應用程式路徑時,才使用 SPA 備援。
- 若希望對文字資產進行壓縮,請開啟 gzip;否則請保持關閉,並仰賴 Nginx 對 HTML 的預設行為。
- 點擊 generate,將產生的 server 區塊複製到 Nginx include 鏈中的預備檔案。第一次嘗試時,請勿直接將區塊放進正式環境。
- 對完整設定執行 nginx -t,確認每個指令都能解析,且每個參考的路徑與模組在已安裝版本中都存在。語法測試通過並不代表檔案權限、DNS、應用程式路由或憑證行為正確,因此下一步至關重要。
- 對預備檔案測試具代表性的請求——包括一個已知的靜態檔案、快取副檔名清單中的資產、應觸發備援的路徑,以及應回傳設定 404 或 SPA 外殼的未知路徑。確認標頭、狀態碼、快取行為與 gzip 的 Vary 標頭都符合預期。
- 在進行任何切換前,備份目前正式環境的設定並記錄使用中的 include 鏈。當平台程序支援時,請改用 reload 而非突然停止服務,並保持一個可復原的 shell 開啟。若語法測試失敗,請勿 reload;若 reload 後請求失敗,請還原備份並檢查錯誤記錄。
針對已安裝模組逐一審核每個指令
產生的區塊會參考核心 HTTP 模組,用於 listen、server_name、root、index、try_files、expires 與 location;啟用壓縮時,則會參考 gzip 模組。兩者皆隨標準 Nginx 套件內建,但自訂編譯可能會排除這些模組,而以動態載入方式建置的模組,必須出現在主設定的 load_module 指令中。部署前,請逐行對照官方模組說明文件進行檢視。ngx_http_core_module 參考文件說明了 listen、server_name、root、index、try_files 與 expires;ngx_http_gzip_module 參考文件則說明了 gzip、gzip_types,以及產生器未覆寫的 gzip_min_length 預設值。
| 指令群組 | 模組參考 | 應驗證項目 |
|---|---|---|
| listen 80, listen [::]:80 | ngx_http_core_module | listen 形式未與同埠上其他區塊衝突 |
| server_name, root, index | ngx_http_core_module | 網域與 DNS 相符;root 路徑存在且可讀取 |
| try_files, expires, Cache-Control | ngx_http_core_module | 備援選擇符合應用程式模型 |
| gzip, gzip_types, Vary | ngx_http_gzip_module | 模組已編譯;回應中出現 Vary 標頭 |
請依你的網路規畫選擇 listen 形式。該區塊會針對單一精確 server_name 輸出 listen 80 與 [::]:80;若你新增額外區塊,請確認其 listen 參數與 server 名稱不會產生 Nginx 拒絕啟動的路由衝突。確認 document root 解析到的目錄在目標伺服器上存在,且 Nginx worker 使用者可讀取——依發行版不同,可能是 root、www-data 或 nginx。確認 asset location 副檔名涵蓋你實際服務的檔案類型,並確保沒有重要資產使用快取 location 會漏掉的副檔名。
若使用較長的快取 duration,請在部署前為長效資產加上指紋或版本編號。為 style.css 設定一年的 expires,會讓訪客在重新設計後仍持有舊檔;同樣的 expires 設定,改用 hashed 檔名 style.a1b2c3.css 即可解決此問題。產生器刻意不會自動加上指紋,因為雜湊值屬於你的建置流程,而非 Nginx 設定的一部分。
為何 nginx -t 本身並不足夠
語法測試會檢查設定檔能否解析、大括號是否平衡、參考的變數與路能否被解析器看見,以及 include 是否成功。它並不會檢查 Nginx worker 行程能否讀取 document root、網域的 DNS 紀錄是否指向你的伺服器、上游應用程式在 try_files 備援時是否回傳預期回應、前端若為 HTTPS 時 TLS 終止是否正常,或 CDN 邊緣是否已套用此次變更。請將 nginx -t 視為防止壞檔被載入的關卡,而非網站運作正常的證明。
語法測試通過後,請測試具代表性的請求。請求一個已知的靜態檔案,確認其以預期的狀態、內容類型與長度回傳。請求位於快取 location 中的已知資產,確認出現 Cache-Control public 與 expires 標頭。請求未知路徑,確認回傳設定的 404 或 SPA 外殼。請求一個依賴 gzip 篩選器的路徑,確認 Content-Encoding 已設定,且回應中出現 Vary: Accept-Encoding。若上述任一檢查失敗,請還原備份並檢查錯誤記錄,之後再進行 reload。
永久性的快取與路由錯誤,即使 Nginx 本身持續上線,仍可能持續影響訪客。錯誤的 root、重複的 server 區塊,或過於寬鬆的 server_name,都可能將真實流量路由到錯誤來源,卻不產生任何 Nginx 錯誤。nginx -t 通過、具代表性請求的煙霧測試,以及一份近期備份,三者的組合,正是在產生器範圍內所能對應的最小安全底線。對於希望深入了解靜態網站設定本身的讀者,建立靜態網站 Nginx 設定指南涵蓋了完整的檔案結構與部署情境。
何時這個產生器是對的工具，何時不是
這個產生器是為了解決一個特定問題而打造的：為靜態網站或單頁應用程式產生一個小型、可稽核的 HTTP 伺服器區塊。如果你的部署符合上述描述——一組有界限、從磁碟提供服務的檔案，並搭配可選的用戶端路由——那麼這個輸出就是正確的起點，而驗證規則也符合你實際上需要在 Nginx 中表達的內容。
當設定的配置表面位於其他位置時，這個產生器就是不對的工具。代管的託管平台、容器映像、Kubernetes 入口控制器，以及 CDN 邊緣節點，它們各自擁有不同的設定語法，將同一個 Nginx 區塊餵入這些系統，可能會產生靜默的錯誤路由或被拒絕的語法。同樣地，需要 TLS、反向代理、應用程式後端、驗證、速率限制、自訂錯誤頁面、MIME 包含路徑、日誌自訂或安全性標頭的網站，需要的是產生器範圍之外的其他指令。請透過託管平台有記載的程序，或是一份獨立的、經過審核的 Nginx 設定（其中將產生器的區塊作為靜態來源部分）來新增這些指令。
最易於維護的成果，是一份最小且經過審核、能對應當前部署證據的設定。一個你已閱讀過、依據模組說明文件稽核過、針對代表性請求做過冒煙測試，並在有備份的情況下才推出的產生區塊，遠比一份憑記憶撰寫、從未審核過的大型設定來得安全。請將產生器的輸出視為你自己審核時的輸入，而不是已經完成的正式環境基準。
如需更深入的瞭解，請參閱 htaccess 轉換至 Nginx：自動化轉換的限制。