htaccess 轉 Nginx rewrite 轉換器會將一個刻意精簡的 Apache .htaccess 指令子集，翻譯成可供審核的 Nginx 指令行，並針對每個不支援的規則回報其原始行號，而不是猜測輸出可能會靜默改變流量的結果。這個工具的重點在於作為伺服器遷移過程中的盤點助手：您貼上一段聚焦的文件根目錄摘錄，轉換器只會輸出它能安全對應的指令，而每個 RewriteCond、不熟悉的旗標或模糊的行，會以手動審核項目的形式回傳給您，而不是大膽地重寫。這種克制很重要，因為 Apache 的每目錄設定模型與 Nginx 的集中式上下文模型並不能互換，一個會靜默寫出看似合理但實際上不等價設定的轉換器，比一個留下明確待辦項目的轉換器更加危險。
從 Apache 遷移到 Nginx —— 或在 Apache 前面跑 Nginx 的人，通常會帶著一堆 rewrite 規則、redirect 指令，以及在 Apache 上運作正常的各式 Options、ErrorDocument 和標頭行來使用這個工具。自然的假設是一次轉換就能產出可運作的 nginx.conf。實際情況是，即使是相同的正規表達式，行為也可能不同，因為兩種伺服器在所匹配的字串、跳脫規則、查詢處理以及迴圈行為上都有差異。一個以審核為先的轉換器承認這個落差，並將遷移轉化為一個有文件記錄的工程步驟，而非大規模的文字取代。
轉換器實際上做了什麼
htaccess 轉 Nginx 轉換器完全在您的瀏覽器中執行。您貼上的摘錄不會被傳送到任何伺服器，因此敏感的規則集可以在本地進行審核。它的範圍刻意精簡：一次解析一條界定的行，忽略 RewriteEngine On，保留註解，並將其支援子集之外的任何內容視為警告而非輸出。
在這個精簡的範圍內，轉換器處理三類指令：
- 具受限旗標集的 RewriteRule。支援的形式是 Apache RewriteRule 樣式、替換內容，以及限於 L、R、R=301 和 R=302 的方括號旗標清單。永久的 Apache redirect 會成為 Nginx 的 permanent 旗標，暫時的 redirect 會成為 redirect，內部的 last 規則會成為 last。
- 三個非 rewrite 指令。Options -Indexes 會成為 autoindex off;，本地的 ErrorDocument 404 路徑會成為帶有相同路徑的 error_page 404，引號框住的 X-Robots-Tag Header set 值會成為一行 add_header。
- 有文件記錄的範圍假設。文件根目錄 .htaccess 中的樣式通常在移除目錄前綴後匹配路徑，因此它們常以插入號開頭但沒有斜線。Nginx rewrite 樣式看到的是以斜線開頭的 URI。轉換器會為支援的根上下文樣式插入那個前置斜線。
其他所有內容都會被回報，而不是輸出。RewriteCond 行永遠不會被自動翻譯，因為其變數、擷取、評估順序和部署情境可能會改變語意；抑制條件後面的規則可以防止一個無條件的 redirect 改變流量。QSA、END、F、G、B 或 NC 等未知旗標會停止該規則的轉換，因為其細節無法安全地被抹除。以單一破折號表示的 Apache 無替換目標也會被保留，因為它經常與改變存取或處理但不更動 URI 的旗標組合使用。
如何轉換一段聚焦的 .htaccess 摘錄
- 貼上一段聚焦的文件根目錄摘錄。開啟 htaccess 轉 Nginx 轉換器，貼上您要遷移的特定區塊，並把不相關的片段留到另一輪處理。讓輸入小到每個輸出行都能用手動審核。
- 審核每個輸出的 Nginx 行。逐行檢視輸出，確認旗標對應符合您的意圖：永久 redirect 對應到 permanent，暫時 redirect 對應到 redirect，內部 last 對應到 last。$1 這類擷取反向引用應原樣保留，因為 Nginx 使用相同的 $1 語法。
- 處理每個帶行號的警告。每個警告會指向原始的 Apache 行號。開啟該行的 Apache mod_rewrite 介紹以及 Nginx rewrite 模組參考文件，判斷這個規則實際在做什麼，如果該規則確實屬於您的 Nginx 設定，就手動遷移它。
- 合併到正確的 Nginx 上下文。輸出是一個片段，而不是完整的 nginx.conf。請根據您實際的應用程式架構，將每個審核過的行放入適當的 server 或 location 區塊中。伺服器層級的 redirect 屬於 server { } 區塊；路徑特定的 rewrite 屬於 location { } 區塊內部。
- 備份並驗證。儲存一份現用設定的副本，對組合後的檔案執行 nginx -t，並保持一個還原工作階段可用。只在測試環境或可逆的維護時段內對代表性請求進行測試 —— 絕對不要在線上正式網站上測試。
哪些會被對應，哪些會產生警告
輸出與警告之間的界線，是理解這個轉換器最重要的一點。下表摘錄了您會遇到的最常見指令其有文件記錄的行為。
| Apache 指令 | 轉換器行為 | Nginx 結果 |
|---|---|---|
| RewriteRule pattern target [L] | 輸出 | rewrite ^pattern target last;，會插入前置斜線 |
| RewriteRule pattern target [R=301] | 輸出 | rewrite ^pattern target permanent; |
| RewriteRule pattern target [R=302] | 輸出 | rewrite ^pattern target redirect; |
| RewriteRule pattern target [QSA,END,F,G,B,NC] | 警告，無輸出 | 需要手動遷移 |
| RewriteRule pattern - [L]（破折號目標） | 警告，無輸出 | 需要手動遷移 |
| RewriteCond ... | 警告，規則被抑制 | 需要手動遷移 |
| Options -Indexes | 輸出 | autoindex off; |
| ErrorDocument 404 /path.html | 輸出 | error_page 404 /path.html; |
| Header set X-Robots-Tag "value" | 輸出 | add_header X-Robots-Tag "value"; |
| 其他狀態碼、外部 ErrorDocument、條件式標頭、環境變數、指令容器 | 警告，無輸出 | 需要手動遷移 |
需要手動遷移這個詞值得特別強調。它並不表示該指令無法移植；而是表示轉換器無法在隔離狀態下安全完成。驗證、授權、防盜連、代理邏輯、CMS front-controller 規則以及複雜的條件都屬於這一類，將它們視為大規模文字取代，是遷移失敗最常見的原因。
為什麼手動審核警告才是重點
這些警告不是雜訊。它們是轉換器主要的價值所在，因為每個被抑制的規則都是一個猜測出來的 rewrite 可能會改變流量、產生 redirect 迴圈或暴露路由的地方。RewriteCond 行在實務上是被抑制規則的最大宗來源：Apache 條件可以檢查 HTTPS 狀態、主機名稱、檔案、目錄、查詢字串、標頭和擷取群組，且評估順序很重要。當 RewriteRule 跟在條件後面時，轉換器也會抑制該規則，而不是輸出一個無條件的 redirect。
無替換的破折號目標是另一個經典陷阱。像 RewriteRule pattern - [F] 這樣的規則經常與改變存取或處理但不更動 URI 的旗標組合，而字面上的破折號並不是安全的 Nginx 替代品。輸出 rewrite ^pattern - last; 在語法上有效，但在語意上是錯誤的。針對這些邊角情況的更深入參考，htaccess 轉 nginx 規則、限制與警告速查表涵蓋了真實遷移中最常出現的樣式。
將片段安全地組裝進 nginx.conf
一旦轉換器產出片段，且每個警告都已解決，接下來的工作就是把各行放到正確的上下文中。伺服器層級的 redirect —— 包括典型的 R=301 情況 —— 通常屬於 server { } 區塊內部。路徑特定的 rewrite 屬於 location { } 區塊內部，並應查閱 error_page 的官方 Nginx 說明文件，以確認 error_page 404 在您的架構中適合放在哪裡。
這個片段本身不會建立 http、server 或 location 區塊，不會選擇 listen 連接埠，不會設定 server_name，不會設定 TLS，不會指定文件根目錄，不會保留 PHP 路由，不會處理代理轉發，也不會定義日誌。請將其視為原料：在版本控管的 Nginx 檔案中組合結果，使用 nginx -t 驗證整個組合後的設定，並在重新載入之前，以代表性請求（舊路徑、新路徑、查詢字串、備用主機、HTTPS 行為）進行測試。永久 redirect 需要格外小心，因為瀏覽器與中介層可能會快取它們，所以實務上請先在受控環境中使用暫時 redirect 開始測試，待測試集通過後再切換為永久 redirect。請確認回應的 Location 標頭，而不是只依賴瀏覽器的網址列。
如果來源包含驗證、授權、防盜連、代理邏輯、CMS front-controller 規則或複雜條件，請將這次遷移視為工程工作，而非大規模文字取代。針對每個非平凡的規則，請同時閱讀 Apache 與 Nginx 的說明文件。一次失敗的重新載入或 redirect 迴圈可能會讓公開網站無法使用，而最安全的工作流程，是新設定中的每一行要不是來自經過驗證的轉換器輸出，就是依照官方說明文件手動撰寫。