一款針對靜態網站的 Nginx 設定產生器替代方案，會根據單一網域、絕對文件根目錄、快取時間，以及選用的 gzip 設定，產生一個經過驗證的 HTTP 伺服器區塊——不會產生不安全的 TLS 假設，也不會產生應用程式後端設定。與試圖涵蓋所有使用情境的廣泛設定工具不同，這項工具專注在一個範圍狹窄、可供稽核的片段，用於靜態檔案或單頁應用程式（SPA）。它會強制要求精確的伺服器名稱、拒絕帶有注入形式的輸入，並輸出一個只在 IPv4 與 IPv6 的連接埠 80 上監聽的區塊。這種做法，能確保設定與部署證據相符，同時避免虛擬主機路由，或可能破壞正式環境的憑證涵蓋範圍猜測。

靜態網站與 SPA，經常有相似的 Nginx 需求：固定的文件根目錄、可預期的資源快取，以及找不到檔案時的後備行為。然而，把這些行為混在一起，可能會造成問題。舉例來說，在內容型網站上啟用 SPA 後備機制，可能會讓失效的網址回傳 200 狀態，讓監控工具偵測不到錯誤。這個產生器透過要求您做出明確選擇——靜態 404 或 SPA 後備——來處理這個問題，讓輸出結果與網站實際的架構相符。快取時間（1 到 365 天）只適用於一份範圍有限的副檔名清單（CSS、JavaScript、圖片、字型），但較長的快取時間，需要搭配版本化或加上指紋的資源，以避免部署後出現過時檔案。選用的 gzip 壓縮，會加上 Vary: Accept-Encoding，並涵蓋標準類型，但 HTML 則交由 Nginx 的預設行為處理，以避免重複設定。

這項工具的限制是刻意設計的。它不涵蓋 TLS、PHP、FastCGI、反向代理，以及安全性標頭，因為這些都取決於部署層級的細節，例如憑證路徑、憑證更新工具，或代理拓撲。憑空捏造這些內容，只會製造出虛假的信心，因此這個產生器把它們留給經過審查的伺服器程序去處理。同樣地，它也不涵蓋萬用字元網域、替代的 www 主機，或 server_name 的正規表示式，因為這些都會影響路由與憑證涵蓋範圍。如果需要有多個名稱提供服務或轉址，您必須明確設計那個行為，而不是依賴產生器去推測擁有權。文件根目錄必須是一個含有安全字元的絕對 POSIX 路徑；瀏覽器無法驗證它在目標伺服器上是否存在，或權限設定是否正確，因此仍然需要人工檢查。您可以試試Nginx 設定產生器，在您的瀏覽器中完成這件事。

nginx config generator alternative
Nginx 設定產生器替代方案

什麼時候該用這個工具，而不是廣泛型的產生器

廣泛型的 Nginx 設定產生器，經常因為對 TLS、應用程式後端，或萬用字元網域做出假設，而產生臃腫或不安全的區塊。這些假設，可能會導致設定錯誤，例如錯誤的憑證路徑，或非預期的虛擬主機路由。Nginx 設定產生器透過專注在單一的靜態網站或 SPA 使用情境，避開了這些陷阱。它會拒絕不安全的輸入，例如分號、大括號，或變數，因為這些可能會產生額外的指令，或造成語法錯誤。輸出結果，是一個精簡、隨時可供審查的區塊，符合目前部署的需求，而不會去猜測未來可能的需求。

舉例來說，如果您的網站是一個靜態部落格，或是一個 React/Vue 的 SPA，這個產生器的有限範圍做法，能確保設定既正確又容易維護。它不會加入不必要的 PHP、FastCGI，或反向代理指令，因為這些指令如果沒有被用到，只會讓除錯變得更複雜。這項工具也會強制要求精確比對 server_name，避免與同一台伺服器上的其他虛擬主機發生衝突。如果您需要 HTTPS，就必須透過您的主機平台，或經過審查的程序另外設定，因為憑證路徑與更新工具，在不同的部署環境中各不相同。

當您的目標，是為靜態網站或 SPA，取得一個小型、可供稽核的 Nginx 區塊時，就適合使用這項工具。如果您需要 TLS、應用程式後端，或複雜的路由規則，就不適合使用它——那些需要人工設定，或更專門的工具。對於受管理的主機代管、容器，或以 CDN 為基礎的部署，正確的設定介面可能位於別處，例如 Kubernetes ingress，或平台專屬的控制台。

如何為靜態網站產生 Nginx 設定

  1. 輸入確切的網域與文件根目錄。 提供一個網域（例如 example.com）與一個絕對 POSIX 路徑（例如 /var/www/example.com/html）。這項工具會拒絕帶有通訊協定的網域（例如 https://example.com），或不安全的路徑字元，例如分號或大括號。這個路徑必須存在於目標伺服器上，並具備正確的擁有權與讀取權限，但瀏覽器無法驗證這一點——您必須自行手動檢查。

  2. 設定快取時間與後備行為。 為靜態資源（CSS、JavaScript、圖片、字型），選擇 1 到 365 天之間的快取時間。對於靜態網站，請選擇 404 作為後備方式。對於 SPA，請啟用 SPA 後備機制，把未知路徑導向 /index.html。請勿在內容型網站上啟用 SPA 後備機制，因為它可能會讓失效的網址被隱藏起來。

  3. 啟用 gzip（選用）。 如果您的網站提供可壓縮的資源，請啟用 gzip。這項工具會加上 Vary: Accept-Encoding，並列出標準類型（CSS、JavaScript、JSON、SVG）。HTML 由 Nginx 的預設 gzip 行為處理，因此不會出現在 gzip_types 中。請評估您網站的壓縮需求，因為 gzip 可能會為回應中的機密資訊，帶來旁路風險。

  4. 產生並審查這個區塊。 點擊產生，以產生伺服器區塊。這項工具會針對已安裝的 Nginx 模組、部署路徑，與快取策略，驗證每一項指令。請審查輸出結果是否正確，特別是 root、try_files 與 expires 指令。這個區塊只在 IPv4 與 IPv6 的連接埠 80 上監聽，並使用精確的 server_name——沒有萬用字元或正規表示式。

  5. 備份您目前使用中的設定。 在部署之前，請先儲存目前的 Nginx 設定，並記錄目前使用中的 include 鏈。這樣一來，如果新的區塊造成問題，您就能還原到先前的狀態。請把產生出來的片段，放在您 Nginx 安裝環境中正確的情境位置，例如 /etc/nginx/sites-available/example.com。

  6. 測試語法與實際請求。 執行 nginx -t 來驗證完整的設定。語法測試成功，並不保證檔案權限、DNS，或應用程式路由都正確，因此請對具代表性的路徑（例如 /、/about、/nonexistent）發出請求，以驗證行為是否正確。如果測試失敗，請不要重新載入 Nginx——先還原備份，並檢查錯誤日誌。

  7. 重新載入 Nginx 並持續監控。 如果語法測試通過，且實際請求也成功，請依平台的程序（例如 systemctl reload nginx），重新載入 Nginx。請保留一個復原用的 shell 開啟，以備發生問題時使用。如果重新載入後請求失敗，請立即還原備份，並檢查錯誤日誌，找出權限、路徑，或路由方面的問題。

產生出的區塊中的關鍵指令

指令 用途 範例值 備註
listen 定義伺服器區塊使用的 IP 與連接埠。 80; listen [::]:80; 只在 IPv4 與 IPv6 的連接埠 80 上監聽。不含 TLS。
server_name 比對這個區塊所使用的確切網域。 example.com; 沒有萬用字元或正規表示式。每個區塊只能有一個網域。
root 設定絕對的文件根目錄路徑。 /var/www/example.com/html; 必須是含有安全字元的絕對 POSIX 路徑。
try_files 定義找不到檔案時的後備行為。 $uri $uri/ =404;（靜態）或 $uri $uri/ /index.html;（SPA） SPA 後備機制，只應該用於用戶端路由。
expires 設定靜態資源的快取時間。 30d; 適用於一份固定的副檔名清單（CSS、JS、圖片、字型）。
gzip 為支援的類型啟用壓縮。 on; 加上 Vary: Accept-Encoding，並涵蓋標準類型。

需要留意的陷阱

即使使用經過驗證的產生器，小小的疏忽仍可能破壞您的 Nginx 設定。以下是最常見的問題，以及如何預防它們：

  • 假設文件根目錄已經存在。 這個產生器只會驗證路徑格式，無法檢查它在目標伺服器上是否存在，或權限是否正確。請務必手動驗證這個路徑，並確認 Nginx 工作處理程序（例如 www-data）具有讀取權限。即使語法測試通過，缺少權限仍會造成 403 錯誤。

  • 在內容型網站上啟用 SPA 後備機制。 SPA 後備機制，會把未知路徑導向 /index.html，這可能會隱藏失效的網址，並讓遺失的資源回傳 200 狀態。請只在用戶端路由（例如 React、Vue、Angular）時使用這個機制。對於靜態網站，請保留真正的 404，以維持錯誤語意與 SEO。

  • 使用較長的快取時間，卻沒有替資源做版本化。 這個產生器允許的快取時間，最長可達 365 天，但較長的快取時間，可能會在部署後提供過時的檔案。在使用較長的快取時間之前，請務必為資源加上指紋或版本標記（例如 styles.v2.css）。如果沒有版本化，訪客可能會一直看到過時的內容，直到他們的快取過期為止。

  • 略過實際請求測試。 一次成功的 nginx -t 測試，只驗證語法與檔案參照是否正確，但無法驗證 DNS、檔案權限，或應用程式路由是否正確。請務必在重新載入後，對具代表性的路徑（例如 /、/about、/nonexistent）發出請求，以確認網站行為符合預期。

  • 忽略 include 鏈。 產生出來的區塊，必須放在您 Nginx 安裝環境中正確的情境位置。遺漏或放錯位置的 include 指令，可能會導致這個區塊無法被載入。部署之前，請先記錄目前使用中的 include 鏈，並確認新的檔案，已在主要設定中被參照（例如 /etc/nginx/nginx.conf）。

  • 假設已經包含 TLS。 這個產生器刻意不涵蓋 TLS，以避免對憑證路徑、更新工具，或代理拓撲做出不安全的假設。請透過您的主機平台，或經過審查的伺服器程序，另外設定 HTTPS，接著測試 HTTP 轉 HTTPS 的轉址，以及 HSTS 政策。

如需更多關於安全部署 Nginx 設定的詳細資訊，請參閱我們關於如何取得一份真正可以部署的 Nginx 設定檔的指南。

進階使用情境的替代方案

Nginx Config Generator 是為靜態網站與 SPA 而設計的,但對於進階需求,其他工具或手動做法可能更合適:

  • 涵蓋範圍廣泛的 Nginx 產生器。像 nginxconfig.io(外部網站)這類工具涵蓋 TLS、應用程式後端與萬用字元網域,但它們會做出一些可能與你的部署方式不符的假設。只有在你需要這個產生器範圍以外的功能、且準備好徹底檢視輸出結果時,才使用這類工具。

  • 手動設定。對於複雜的架構(例如反向代理、WebSocket、身分驗證),請參考official Nginx core module documentation手動撰寫設定。這能確保每一條指令都與你的架構相符,並避免出現冗餘或不安全的區塊。

  • 受管理的主機或 CDN。像 Vercel、Netlify 或 Cloudflare 這類平台會自動處理 Nginx 設定。在這些平台上,正確的設定介面可能是儀表板或 CLI 工具,而不是手動撰寫的設定區塊。請查閱你所使用服務商的文件,尋找針對靜態網站或 SPA 的專屬指南。

  • Kubernetes ingress。如果你是在 Kubernetes 上部署,請使用 ingress controller(例如 Nginx Ingress、Traefik),而不是手動撰寫 Nginx 區塊。Ingress 資源以宣告式的格式定義路由規則、TLS 與後端,能減少手動撰寫設定的需求。

若要把 Apache 的 .htaccess 檔案轉換成 Nginx 格式,我們的htaccess to Nginx converter會轉換一小部分指令,同時標示出不支援的規則。這對於遷移舊有設定很有幫助,但對於複雜的架構仍需要人工檢視。

如需深入了解,請參閱Nginx Config Generator API Alternative: No Server Calls。