將 .htaccess 轉換為 nginx 僅涵蓋一小部分有明確文件的 Apache 指令,所有條件式或不支援的規則都會以其原始行號回報,而不是被靜默地重寫。htaccess 轉 Nginx 轉換器是圍繞著這個狹窄的合約所建構:它接受一個聚焦的文件根目錄摘錄,轉換它知道如何處理的規則,並對任何需要人為判斷的內容提出警告。Apache 的 mod_rewrite 與 Nginx 的 ngx_http_rewrite_module 共享詞彙但語意不同,因此一個會輸出看起來合理但實際上不等價的設定的轉換器,可能會破壞路由、產生重新導向循環,或暴露先前受到保護的路由。因此這個工具刻意保持精簡。它處理永久與暫時的重新導向、L 旗標、文件根目錄模式調整、停用目錄列表、本機 404 處理以及 X-Robots-Tag 標頭,並回報所有其他項目。將輸出視為已審閱的片段——絕非即裝即用的 nginx.conf——這正是讓遷移安全的關鍵。當來源 .htaccess 包含身分驗證、代理邏輯或 CMS front-controller 規則時,轉換器會將其留給人工處理,因為這類遷移屬於工程工作,而非大量文字取代。
為何直接的 htaccess 轉 nginx 轉換無法是通用的
Apache 在請求處理期間走訪目錄樹時會發現 .htaccess 檔案。只要 AllowOverride 允許,每個請求都可能觸發一次重新剖析,這就是為何 per-directory 覆寫、mod_rewrite 與身分驗證檢查通常會以 .htaccess 表示。Nginx 完全不這麼做。伺服器在啟動時讀取集中化的設定、在請求進入 rewrite 階段之前評估 server 與 location 上下文,並將 per-directory 設定視為 Nginx 為了效能而刻意省略的設計選擇。兩台伺服器會針對不同的字串、以不同的跳脫規則、不同的查詢處理方式與不同的循環行為,比對外觀相同的正規表示式。
實際上的後果是:任何聲稱能將 .htaccess 翻譯成 nginx 的工具都必須畫一條界線。一個會將 RewriteCond 靜默重寫成無條件區塊,或猜測某個未知旗標代表某種合理意義的轉換器,可能會讓一個公開網站停擺。htaccess 轉 Nginx 轉換器公開地畫出了這條界線:支援一組固定的指令子集,任何超出範圍的內容都會連同原始行號一起回報,讓操作者能對照官方 Apache 與 Nginx 文件進行處理。
轉換器會翻譯的指令
轉換合約涵蓋三種 rewrite 旗標組合、一個目錄列表控制項、一個本機錯誤頁面以及一個回應標頭。任何超出此集合的內容都不會自動轉換。
| Apache .htaccess 指令 | 輸出的 Nginx 等效項目 | 備註 |
|---|---|---|
| RewriteRule pattern target [R=301] | rewrite ^pattern /target permanent; | 永久重新導向;可被瀏覽器與中介層快取。 |
| RewriteRule pattern target [R=302] 或 [R] | rewrite ^pattern /target redirect; | 暫時重新導向;對分階段推出較為安全。 |
| RewriteRule pattern target [L] | rewrite ^pattern /target last; | 內部 rewrite,終止後續規則處理。 |
| Options -Indexes | autoindex off; | 在轉換後的上下文中停用目錄列表。 |
| ErrorDocument 404 /path | error_page 404 /path; | 僅限本機路徑;轉換器不支援外部 URL。請參閱Nginx error_page 指令以了解放置規則。 |
| Header set X-Robots-Tag "value" | add_header X-Robots-Tag "value"; | 必須使用引號值;不轉換條件式標頭。 |
超出自動支援集合的 RewriteRule 旗標——例如 QSA、END、F、G、B、NC 等——會停止該規則的轉換並顯示警告。僅包含支援項目的括號旗標清單則會正常進行。
轉換器拒絕猜測的內容
有三類輸入一律會產生警告而非猜測的輸出,因為猜測這些內容會靜默地改變流量行為。
- RewriteCond 行。Apache 條件可以檢查 HTTPS 狀態、主機名稱、檔案、目錄、查詢字串、標頭與擷取群組,其評估順序會與 rewrite 引擎互動。當 RewriteRule 接在某條件之後時,工具也會一併抑制該規則,而不是輸出可能改變流量、產生循環或暴露路由的無條件重新導向。
- 未知的 RewriteRule 旗標。支援集合以外的旗標會改變存取、處理程序或回應主體。其語意無法透過翻譯抹除,因此轉換器會回報原始行號並停止。
- 破折號目標。替代內容為單一 - 的 Apache 規則,通常會搭配改變存取或處理程序(但不改變 URI)的旗標使用。常值破折號並非安全的 Nginx 替代項目,因此該規則會被保留並輸出警告。
轉換器不處理的其他輸入:身分驗證與授權指令、防盜連(熱連)保護、代理設定、CMS front-controller 規則、環境變數操作,以及指令容器。將任何包含這些項目的遷移視為工程工作,而非大量文字取代。
如何使用 htaccess 轉 Nginx 轉換器
- 開啟 htaccess 轉 Nginx 轉換器,並貼上來自單一文件根目錄 .htaccess 檔案的聚焦摘錄。請保持貼上內容短到能以肉眼審閱;若超過一頁螢幕,請將其拆成較小的摘錄。
- 同時閱讀轉換後的輸出與附帶行號的警告。每個警告都會對應到 Apache 摘錄中的原始行號,讓您無須搜尋即可定位該規則。
- 針對每個警告,參考 Apache mod_rewrite 介紹以及相關的 Nginx 文件進行人工處理。判斷該規則需要的是 rewrite、map、受控上下文中的 if 區塊,或是完整的重新設計。
- 將核准的指令行組合成為一個版本受控的 Nginx 設定檔。請將 rewrite 與 error_page 行放置於網站正確的 server 或 location 區塊中,而非檔案頂端。
- 備份現行有效的設定,對組裝完成的檔案執行 nginx -t,並在任何重新載入之前對代表性請求進行預演。類似 如何取得一個真正能用的 Nginx 設定 的指南,會在您從零開始時,逐步說明靜態網站的周邊上下文選擇。
輸出在 Nginx 中應放置的位置
轉換器輸出的片段並未定義 listen 連接埠、server_name、TLS、文件根目錄、upstream、PHP 處理程式或 log 指令。這些都是取決於實際應用程式與周邊架構的決策,工具刻意不會代為決定。每行輸出的指令都必須依照 Nginx 指令參考所指定的位置放置。
rewrite 與 error_page 行通常應置於 server 區塊中,而更具針對性的規則可限定於符合相關 URI 前綴的 location 區塊。autoindex off 與 add_header 可依規則適用範圍的廣度,放置於 http、server 或 location 層級。若 Apache 來源使用了不以開頭斜線開頭的 RewriteRule 模式(在文件根目錄 .htaccess 中很常見),轉換器會在輸出時補上該開頭斜線,因為 Nginx rewrite 模式所看到的是以 / 開頭的 URI。這是針對文件根目錄檔案的文件化範圍假設,並非適用於巢狀 .htaccess 或 Alias 對應的通用轉換。
不停機地驗證與重新載入
即使是語法正確的 Nginx 行,也可能不適合其所在的上下文,這就是為何驗證比轉換本身更重要。最低限度以下的安全流程:
- 將目前正式環境的設定保留為可復原的備份,並保持一個開啟的復原工作階段,以防新檔案無法載入。
- 對組裝完成的設定執行 nginx -t。此工具會回報語法錯誤,但無法偵測語法正確卻在該上下文中語意錯誤的指令行。
- 在預備環境,或於維護旗標之後,對代表性請求進行測試。涵蓋舊路徑、新路徑、查詢字串、其他主機與 HTTPS 行為。
- 確認回應的 Location 標頭,而不是僅依賴瀏覽器網址列,尤其在涉及重新導向時。
永久重新導向需要格外小心,因為瀏覽器與中介層可能會加以快取,因此一條錯誤的永久規則可能要花好幾天才能撤銷。在可行的情況下,請先在受控環境中使用 redirect(暫時),待重新導向矩陣驗證無誤後再切換為 permanent,並保留暫時版本以便隨時回復。一次失敗的重新載入或重新導向循環可能會迅速讓公開網站下線,而一條被快取的永久重新導向可能會讓客戶端持續保留它,讓網站長時間離線。
htaccess 轉 Nginx 轉換器是為該流程的第一階段所設計:一段聚焦的摘錄、一小組支援的規則、針對其餘部分的附行號警告,以及坦誠表明自己僅是一個片段的輸出。任何更龐大的企圖——身分驗證、代理、CMS front-controller rewrite、條件邏輯——都應透過人工方式對照 Apache 與 Nginx 文件進行遷移,而非交由批次轉換處理。
如果您正在權衡各項選擇,如何取得您能真正部署的 Nginx 設定檔對此有詳細說明。