htaccess 轉 Nginx 轉換器是一個以瀏覽器為基礎的工具，它會將刻意限定的、可稽核的 Apache .htaccess 指令子集，轉換為可供審閱的 Nginx 設定行，並把所有條件或不支援的規則全部標示出來，而非自行猜測。與通用的 rewrite 轉換器不同，此工具拒絕靜默地忽略它無法處理的指令；它會以帶有行號的警告標示這些指令，迫使你必須逐一對照 Apache 官方文件和 Nginx 官方文件手動處理。最終會產生一個透明、可稽核的轉換結果，正符合從 Apache 遷移至 Nginx 的開發者需求，且不會繼承隱藏的相容性風險。

情境很重要：Apache 的 .htaccess 檔案是每目錄（per-directory）的設定片段，會覆寫全域設定；而 Nginx 則不使用每目錄覆寫，而是採用單一的集中式設定檔。這種結構上的差異意味著一對一的重寫幾乎不可能。取而代之，轉換器僅對應 Nginx 能在 server 或 location 區塊中表達的指令——rewrite 規則、存取控制、MIME 類型，以及基本快取——同時明確拒絕 .htaccess 中如 .htpasswd 認證或 mod_php 設定等功能。透過縮小範圍，此工具能確保每一行輸出的設定在語法上正確，且語意上等同於原本的 Apache 意圖。

為何這種做法有效：通用的線上轉換器往往嘗試轉譯每一條指令，包括那些 Nginx 根本無法複製的指令。結果就是產生一份看似正確，但在實際流量下卻會靜默失效的設定。相對地，本文件採用的 htaccess 轉 Nginx 轉換器拒絕猜測。它會以清楚的警告列出每一條不支援的規則，迫使你要麼改用 Nginx 原生語法重寫邏輯，要麼接受該功能無法移植。這種透明度對於正式（production）環境至關重要，因為未被偵測到的錯誤設定可能導致連結失效、安全漏洞或效能下降。

apache htaccess to nginx converter
apache htaccess to nginx 轉換器

何時該使用 .htaccess 轉 Nginx 轉換器

當你正在將一個靜態網站、PHP 應用程式，或像 WordPress 這類的 CMS，從 Apache 伺服器遷移至 Nginx 伺服器，且需要保留 URL rewrite、存取控制或 MIME 類型覆寫時，請使用本工具。常見的情境包括：

  • 將帶有永久連結（permalink）規則的 WordPress 網站從 Apache 移植到 Nginx。
  • 遷移仰賴 .htaccess 進行 URL 路由或基於 IP 的存取限制的舊版 PHP 應用程式。
  • 將多個位於不同目錄的 .htaccess 檔案整合成單一的 Nginx server 區塊。
  • 在正式投入完整遷移之前，先測試伺服器轉換的可行性。

如果你的 .htaccess 檔案包含 Nginx 無法複製的指令，例如 .htpasswd 認證、mod_php 設定，或每目錄的 PHP 設定，則不應使用本工具。在這種情況下，你將需要改用 Nginx 原生的替代方案來重新設計該功能，例如 HTTP 基本認證或 fastcgi_pass 指令。

支援與不支援的 .htaccess 指令

此轉換器僅支援 Apache .htaccess 中在 Nginx 裡有直接或近乎直接對應項的狹窄子集。不支援的指令會以警告標示，讓你可以手動處理。以下是支援與不支援指令的對照：

類別 支援的指令 不支援的指令
Rewrites RewriteEngine, RewriteRule, RewriteCond, RewriteBase None
Access Control Order, Allow, Deny, Require, Satisfy AuthType, AuthName, AuthUserFile, Require valid-user
MIME Types AddType, AddEncoding None
Caching ExpiresActive, ExpiresDefault, ExpiresByType Header set Cache-Control
Directory Index DirectoryIndex None
Error Documents ErrorDocument None

對於不支援的指令，你將需要改用 Nginx 原生的替代方案來重新設計該功能。例如，.htpasswd 認證可改用 Nginx 的 HTTP Basic Authentication 取代，而 PHP 設定則必須移到 fastcgi_pass 區塊中。

如何逐步將 .htaccess 轉換為 Nginx

請依照下列步驟，使用 htaccess 轉 Nginx 轉換器，將你的 Apache .htaccess 檔案轉換為 Nginx 設定行：

  1. 準備一份聚焦的 .htaccess 摘錄：僅從文件根目錄的 .htaccess 檔案中，複製你需要轉換的指令。請避免包含位於巢狀目錄中的指令，因為 Nginx 並不支援每目錄覆寫。如果你的 .htaccess 檔案包含不支援的指令（例如 .htpasswd 認證），請先將其移除，或稍後再規劃重新設計。
  2. 貼入轉換器：開啟 htaccess 轉 Nginx 轉換器，並將你的摘錄貼到輸入欄位中。按下「Convert」以產生 Nginx 輸出。該工具只會輸出支援的指令，並以帶有行號的警告標示任何不支援的規則。
  3. 檢閱輸出結果：逐行檢視輸出的 Nginx 設定及其對應的警告。例如，若轉換器將某條 RewriteCond 標示為不支援，你將需要使用 Nginx 的 rewrite 模組或 if 陳述式來重寫邏輯。請交叉比對原始的 Apache 指令與 Nginx 官方文件，以確保語意上的等價性。
  4. 合併至正確的 Nginx 上下文：將轉換後的設定行複製到合適的 Nginx server 或 location 區塊中。例如，rewrite 規則通常應置於 server 區塊，而存取控制則可能應置於 location 區塊。請避免將指令放錯位置，否則可能導致語法錯誤或非預期的行為。
  5. 備份你目前正在使用的設定檔：在進行變更之前，請先備份你目前的 Nginx 設定檔。這樣可以確保一旦新設定造成問題時，能夠快速還原。請使用類似以下的指令： 
    sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak
  6. 測試設定：執行下列指令來測試新 Nginx 設定的語法： 
    sudo nginx -t
    若測試失敗，請檢視錯誤訊息並修正語法後再繼續。若測試通過，請重新載入 Nginx 以套用變更： 
    sudo systemctl reload nginx
  7. 測試具代表性的請求：使用 Link Extractor（連結擷取器）這類工具來產生一份網站 URL 清單，再手動測試其中一部分 URL，確認它們都能正確解析。請特別留意依賴 rewrite 規則的 URL，因為這類 URL 在遷移過程中最容易出錯。

常見陷阱與避免方法

從 Apache 遷移至 Nginx 並非毫無風險。以下列出常見的陷阱以及避免策略：

  • 假設所有指令皆受支援：許多 .htaccess 功能，例如 .htpasswd 認證或 mod_php 設定，在 Nginx 中並無直接對應。轉換器會將這些不支援的指令標示出來，但你必須改用 Nginx 原生的替代方案來重新設計它們。例如，將 .htpasswd 改用 Nginx 的 HTTP Basic Authentication 模組。
  • 忽略上下文的差異：Apache 的 .htaccess 檔案會套用至其所在的目錄及其所有子目錄，而 Nginx 設定則是集中式的。這代表你必須手動將位於巢狀 .htaccess 中的指令合併到合適的 Nginx server 或 location 區塊中。否則可能導致設定遺漏或出現安全漏洞。
  • 忽略語法上的差異：Nginx 在 rewrite 規則、存取控制及 MIME 類型的語法上與 Apache 不同。例如，Apache 的 RewriteRule ^(.*)$ index.php?url=$1 [QSA,L] 在 Nginx 中會變成 rewrite ^/(.*)$ /index.php?url=$1 last;。請務必交叉比對輸出的設定行與 Nginx 官方文件，以確保正確性。
  • 略過測試階段：即使是一份語法正確的 Nginx 設定，仍可能在實際流量下出錯。請務必測試具代表性的請求，包括依賴 rewrite 規則、存取控制及 MIME 類型覆寫的 URL。可使用 Sitemap URL Extractor（網站地圖 URL 擷取器）這類工具來產生用於測試的 URL 清單。
  • 忘記備份：在對 Nginx 設定進行任何變更之前，請務必先備份目前使用的設定檔。這樣可以確保一旦新設定造成問題時，能夠快速還原。一個簡單的備份指令如下： 
    sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak

範例：將 WordPress 的 .htaccess 轉換為 Nginx

WordPress 大量仰賴 .htaccess 來處理永久連結的 rewrite。以下是一個典型 WordPress .htaccess 檔案及其經轉換後對應的 Nginx 設定範例：

Apache .htaccess：

# BEGIN WordPress
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>
# END WordPress

對應的 Nginx 設定：

location / {
    try_files $uri $uri/ /index.php?$args;
}

在這個範例中，轉換器會將 Apache 的 rewrite 規則轉譯為 Nginx 的 try_files 指令，達到相同的效果：若靜態檔案存在則直接提供，否則 fallback 至 index.php 來處理動態請求。轉換器同時會將 <IfModule> 指令標示為不支援，因為 Nginx 並不使用條件式區塊來載入模組。

手動轉換的替代方案

如果轉換器標示出太多不支援的指令，或你偏好更自動化的方式，可考慮以下替代方案：

  • 手動重新設計：對於複雜的 .htaccess 檔案，可使用 Nginx 原生指令手動重新設計其邏輯。這種方式讓你擁有完全的控制權，但需要對 Apache 與 Nginx 兩者的設定都有深入的了解。請參考 Nginx 官方文件以取得指引。
  • 第三方工具：像 Winginx 這類的工具提供更全面的 .htaccess 轉 Nginx 轉換功能，但它們對於不支援指令的標示可能不夠清楚。請務必手動檢閱輸出結果並進行完整測試。
  • 伺服器遷移服務：若你正在遷移一個規模龐大或複雜的網站，可考慮聘請專業的伺服器遷移服務。這類服務會處理整個遷移流程，包括 .htaccess 轉換、設定測試以及遷移後的支援。

Best Practices for Nginx Configuration

Once you have converted your .htaccess file to Nginx, follow these best practices to ensure a secure, performant configuration:

See also: Create a Secure .htaccess File for HTTPS and Custom 404 Pages.

  • Use include files for modularity: Break your Nginx configuration into modular include files (e.g., rewrites.conf, security.conf) to improve readability and maintainability. Include these files in your main nginx.conf using the include directive.
  • Enable gzip compression: Compress text-based responses (HTML, CSS, JavaScript) to reduce bandwidth usage and improve load times. Add the following to your server block: 
    gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
  • Set proper cache headers: Use the expires directive to set cache headers for static assets. For example: 
    location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
    expires 30d;
    add_header Cache-Control "public, no-transform";
}
  • Restrict access to sensitive files: Block access to sensitive files like .env, .git, or wp-config.php using location blocks. For example: 
    location ~ /\.(env|git|svn) {
    deny all;
    return 404;
}
  • Enable HTTPS: Use Let’s Encrypt to obtain a free SSL certificate and configure Nginx to serve traffic over HTTPS. Tools like Nginx Config Generator can help you create a secure HTTPS server block.

For a deeper look, see How to Create a .htaccess File for HTTPS Redirects.