htaccess 轉 Nginx 轉換器是一個瀏覽器型輔助工具，它將一個刻意精簡、可稽核的 Apache .htaccess 指令子集，轉譯成可供審閱的 Nginx 設定行，同時列出每一個條件或不支援的規則，而非自行猜測。它並非萬能的匯入工具：它接受一小段 document-root 的 .htaccess 摘錄，一次處理一行有限的內容，略過 RewriteEngine On，保留註解，並且只輸出其轉換合約所涵蓋的指令。支援的項目包括一組受限的 RewriteRule 旗標（L、R、R=301、R=302）、三個非重新導向對應（Options -Indexes、本地 ErrorDocument 404，以及帶引號的 X-Robots-Tag Header set 值），以及在 Apache mod_rewrite 介紹與 Nginx rewrite 模組中記載的根目錄 URI 斜線調整。其餘所有項目——RewriteCond 行為列、不熟悉的旗標（例如 QSA、END、F、G、B 與 NC）、無替換的破折號、認證、環境變數、代理邏輯，以及 CMS front-controller 規則——都會連同原始行號以警告形式回報。輸出的是片段而非完整的 nginx.conf，且處理過程全程在瀏覽器內進行，這使得 htaccess 轉 nginx 在 Windows 上的作業流程能貼近一般的本地端編輯-測試循環，而無需將設定檔送往伺服器。
轉換器會對應的內容，以及它刻意以警告形式呈現的內容
轉換器圍繞著一個小而明確的合約而建置。任何超出該合約的規則都會附上來源行號回報，而非默默改寫。這種精簡的範疇正是在 Windows 上進行 htaccess 轉 nginx 稽核能夠撐下去的關鍵：你可以對照 Apache 與 Nginx 手冊逐條處理警告，而不是反向工程自動化工具所產生的結果。
| 指令或旗標 | 轉換器的處理方式 |
|---|---|
| RewriteEngine On | 略過（Nginx 沒有對應指令） |
| RewriteRule pattern substitution [L] | 轉換為 Nginx rewrite 並加上 last 旗標 |
| RewriteRule pattern substitution [R] | 轉換為 Nginx rewrite 並加上 redirect 旗標 |
| RewriteRule pattern substitution [R=301] | 轉換為 Nginx rewrite 並加上 permanent 旗標 |
| RewriteRule pattern substitution [R=302] | 轉換為 Nginx rewrite 並加上 redirect 旗標 |
| RewriteCond 行為列 | 以警告回報；後續規則會被抑制 |
| L、R、R=301、R=302 以外的旗標（QSA、END、F、G、B、NC 等） | 以警告回報；該規則停止轉換 |
| 帶單一破折號替換值的 RewriteRule | 以警告回報；不輸出任何內容 |
| Options -Indexes | 轉換為 autoindex off |
| ErrorDocument 404 /local-path | 轉換為 error_page 404 /local-path |
| Header set X-Robots-Tag "value" | 轉換為 add_header X-Robots-Tag "value" |
| 註解與空白行 | 保留 |
針對 RewriteCond 行為列採取「抑制規則」的作法是刻意的設計。Apache 條件可以檢查 HTTPS 狀態、主機名稱、檔案、目錄、查詢字串、標頭與擷取群組，且其評估順序與伺服器架構都會影響結果。當 RewriteRule 接在條件之後，若輸出一條無條件的 rewrite，可能會改變流量、造成迴圈，或暴露某個路由。帶行號的警告比一個看似合理但不等價的替代方案更為安全。
為何 htaccess 轉 nginx 在 Windows 上需要專屬的作業流程
Apache 與 Nginx 使用不同的請求處理模型。Apache .htaccess 是透過目錄被找到，並可能受 AllowOverride 停用；Nginx 讀取集中式設定，並在 rewrite 處理前先選定 server 與 location 上下文。即使正則表達式完全相同，行為仍可能不同，因為被比對的字串、跳脫處理、查詢處理與迴圈行為都不一樣。在 Windows 上，有三個實際的細節會進一步擴大這個差距。
首先，原生 Windows 版本的 nginx.conf 通常位於 C:\nginx\conf\nginx.conf，許多團隊會用 PowerShell、Command Prompt、Git Bash 或 VS Code 來編輯。傳給 root、error_page 與日誌檔的路徑參數必須使用正斜線或經跳脘的反斜線；Nginx 的 error_page 指令在 Windows 上接受正斜線，這能避免一類無聲的損壞。其次，行尾字元很重要：將 Linux 風格的 .htaccess 複製貼上到 Windows 編輯器時可能引入 CRLF，而混入 BOM 或混雜的行尾字元會造成令人困惑的 nginx -t 錯誤。第三，在 Windows 上執行 nginx -t 意味著要在一個工作目錄為 C:\nginx 的 shell 中執行 nginx.exe；少了這個條件，nginx -t 會找不到設定檔所預期的相對 include 路徑。
這些細節並不會改變轉換器本身的行為，但會影響你在 Windows 主機上組合、驗證與重新載入設定的方式。請把轉換器視為盤點輔助工具，而非遷移本身。
使用工具轉換一段聚焦的摘錄
轉換器一次只處理一件範圍明確的工作：貼上一小段 document-root 的 .htaccess 摘錄、檢視輸出的行、逐條處理帶行號的警告，然後才把結果組裝進 nginx.conf。所謂聚焦的摘錄，指的是最多幾十行——也就是真正在 document root 執行的規則，而非整個網站的 rewrite 歷史。
- 在瀏覽器中開啟 htaccess 轉 Nginx 轉換器，貼上聚焦的 .htaccess 摘錄（避免巢狀 .htaccess 檔、Alias 對應，以及位置特定的 Nginx 區塊）。
- 確認轉換器回報已轉換的行數與警告數，接著在進行任何後續動作前先閱讀每一行輸出內容。
- 針對每一條帶行號的警告，開啟來源行的 Apache .htaccess，並對照 Apache mod_rewrite 介紹 與 Nginx rewrite 模組說明文件手動處理。
- 將輸出的 Nginx 片段（不含警告）複製到 Windows 主機上 nginx.conf 中適當的 server 或 location 上下文內。
- 備份目前線上的 nginx.conf，從 C:\nginx（或你的安裝根目錄）執行 nginx -t，修妥任何結構錯誤，再於本地 Windows 執行個體上測試具代表性的請求，最後才下達 nginx -s reload。
這個五步驟循環是維持作業流程安全的關鍵。該工具不會執行 nginx -t、不會檢查已安裝的模組、不會探查 include 順序，也無法存取你的伺服器。它只產生一段經審閱的片段，組裝與驗證工作由你在自己的環境中完成。
將片段放到正確的 Nginx 上下文中
輸出內容並非一份完整的設定檔。它不會建立 http、server 或 location 區塊、不會選定 listen 連接埠、不會設定 server_name、不會設定 TLS、不會定位 document root、不會保留 PHP 路由、不會設定 proxy 轉送，也不會定義日誌。你必須依照官方 Nginx 指令說明文件以及實際的應用程式架構，將每一行經審閱的內容放到正確的上下文中。根目錄上下文的斜線調整已直接套用於支援的樣式——轉換器會為其涵蓋的 RewriteRule 旗標組加上前置斜線——但外圍的 server 與 location 區塊仍由你負責。
前置斜線的調整是一個有明文記載的範疇假設：它僅適用於受限的根目錄上下文 RewriteRule 形式，並非巢狀 .htaccess 檔、Alias 對應或位置特定 Nginx 區塊的通用轉換規則。
Windows 測試站台上的永久與暫時重新導向
永久重新導向需要格外小心，因為瀏覽器與中介層可能會加以快取。在 Windows 測試站台，你可以把同一條 rewrite 跑兩次並切換旗標，獨立比較行為。
| 首輪選擇 | Nginx 旗標 | 快取行為 | 何時切換為永久 |
|---|---|---|---|
| 暫時 | redirect | 預設不會被快取 | 確認舊路徑、新路徑、查詢字串、替代主機與 HTTPS 行為皆如預期後 |
| 永久 | permanent | 瀏覽器與中介層可能會快取 | 僅在測試站台完成多次確認並實際檢查 Location 標頭之後 |
請確認回應中的 Location 標頭，而非僅憑瀏覽器網址列判斷。Windows 上的 curl -I（或 PowerShell 5.1 與 PowerShell 7 中的 curl.exe）會列印真實用戶端收到的標頭，包含 Location 欄位。光是這項檢查，就能保護你避開一個可能只在一般使用者碰到快取版頁面時才會顯現的重新導向迴圈。
組裝片段時常見的 Windows 端陷阱
Windows 遷移上大多數的損壞並非出在 rewrite 規則本身，而是出在周圍設定的組裝方式。在下達 nginx -s reload 之前，有幾種狀況經常出現，值得一提。
- 路徑分隔符號。 Nginx 在 Windows 上接受正斜線。在同一行 root 或 error_page 中混用 C:\nginx\html 與 C:/nginx/html，是檔案找不到的常見原因，而非設定解析錯誤。
- 行尾字元。 若編輯器在貼上時引入 CRLF，請將組裝後的 nginx.conf 儲存為一致的 CRLF。檔案開頭若混入 BOM，會導致 nginx -t 產生「unexpected token」錯誤。
- Listen 連接埠衝突。 Windows 服務與多款桌面應用程式歷來會佔用連接埠 80。請在測試階段將 Nginx 綁定至 8080，或在驗證前先停止衝突的服務。
- 先測試再重新載入。 在對外的 Windows 主機上，若 rewrite 有誤就下達 nginx -s reload，可能會讓網站停擺。請務必先執行 nginx -t，再以 curl -I 對具代表性的舊路徑與新路徑進行測試。
- 黏著的快取。 先前快取的 301 可能在你修好設定後仍殘留在瀏覽器中。請使用全新的瀏覽器設定檔、無痕視窗，或 Windows 上的 curl 來驗證暫時重新導向是否已如預期運作。
如果來源中包含認證、授權、熱連結保護、proxy 邏輯、CMS front-controller 規則或複雜的 RewriteCond 條件，請將這次遷移視為工程工作，而非批次文字替換。轉換器是盤點工作的正確起點；但它無法取代這些功能所需的人工審閱。若需要重新載入前可用的聚焦稽核清單，可參考 reload 前稽核作業流程，其中以 Windows 專屬的殼層命令走過相同的驗證順序。