Nginx 支援 .htaccess 實現偽靜態：Include 引入機制、Rewrite 規則轉換與生產級避坑

Nginx 原生不支援 Apache 的分散式配置文件 .htaccess，但通過 include 指令可實現「類 .htaccess」體驗：在項目目錄維護 rewrite 規則，Nginx 主配置引入，實現偽靜態、訪問控制、密碼保護等功能。本文詳細講解引入機制、規則轉換、權限陷阱與最佳實踐。

核心原理：include 指令

# Nginx 主配置 http/Server/Location 上下文均可使用
server {
    listen 80;
    server_name example.com;
    root /var/www/example.com;

    # 引入項目目錄下的 .htaccess (任意文件名)
    include /var/www/example.com/.htaccess;

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

⚠️ 關鍵限制：include 在**配置加載時**靜態展開，**不支援運行時動態讀取**。修改 .htaccess 後**必須 reload Nginx** 生效。若需 Apache 風格的即時生效，請改用 Lua (OpenResty) 或直接編寫 Nginx 原生 rewrite。

.htaccess 規則編寫與 Apache→Nginx 轉換

Apache 原生規則 (Discuz 示例)

# Apache .htaccess
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^archiver/((fid|tid)-[\w-]+\.html)$ archiver/index.php?$1 [L]
RewriteRule ^forum-([0-9]+)-([0-9]+)\.html$ forumdisplay.php?fid=$1&page=$2 [L]
RewriteRule ^thread-([0-9]+)-([0-9]+)-([0-9]+)\.html$ viewthread.php?tid=$1&extra=page%3D$3&page=$2 [L]
RewriteRule ^profile-(username|uid)-(.+)\.html$ viewpro.php?$1=$2 [L]
RewriteRule ^space-(username|uid)-(.+)\.html$ space.php?$1=$2 [L]
RewriteRule ^tag-(.+)\.html$ tag.php?name=$1 [L]

Nginx 等價規則 (.htaccess 文件內容)

# Nginx rewrite 規則 (放入 .htaccess)
# 注意：Nginx 無 RewriteEngine/RewriteBase，直接寫 rewrite 指令
# 正則捕獲用 $1 $2...，標誌位 last/break/redirect/permanent

# 歸檔
rewrite ^(.*)/archiver/((fid|tid)-[\w-]+\.html)$ $1/archiver/index.php?$2 last;

# 論壇列表分頁
rewrite ^(.*)/forum-([0-9]+)-([0-9]+)\.html$ $1/forumdisplay.php?fid=$2&page=$3 last;

# 帖子分頁
rewrite ^(.*)/thread-([0-9]+)-([0-9]+)-([0-9]+)\.html$ $1/viewthread.php?tid=$2&extra=page%3D$4&page=$3 last;

# 用戶資料
rewrite ^(.*)/profile-(username|uid)-(.+)\.html$ $1/viewpro.php?$2=$3 last;

# 空間
rewrite ^(.*)/space-(username|uid)-(.+)\.html$ $1/space.php?$2=$3 last;

# 標籤
rewrite ^(.*)/tag-(.+)\.html$ $1/tag.php?name=$2 last;

轉換關鍵差異表

自動化轉換工具

• 在線工具：anilcetin.com converter (粘貼 Apache 規則輸出 Nginx 規則)
• 命令行：htaccess2nginx (Python 腳本，GitHub 可獲取)
• 人工審核：自動工具僅處理 80% 通用規則，**複雜條件、變量映射、標誌位語義必須人工驗證**

進階用法：.htaccess 非 Rewrite 功能移植

生產級避坑清單

1. 🔴 權限問題：Nginx worker 進程用戶 (www-data/nginx) 必須對 .htaccess 有讀權限 → chown www-data:www-data .htaccess && chmod 644 .htaccess
2. 🔴 路徑遍歷風險：若 .htaccess 可被用戶上傳控制，惡意規則可導致任意文件讀取/內部重定向 → **嚴禁用戶可寫目錄使用 include .htaccess**，僅限部署管控目錄
3. 🟡 性能影響：每請求額外解析 include 文件，高併發下可觀測到 CPU 增長 → 核心規則寫入主配置，僅業務頻變規則放 .htaccess
4. 🟡 語法錯誤導致全站掛掛：.htaccess 語法錯誤會使 nginx -t 失敗、reload 失敗 → **上線前必須 nginx -t 驗證**
5. 🟡 斷點調試困難：Nginx 無 rewrite 日誌等級 (Apache 有 RewriteLog) → 臨時在規則中加 return 200 "DEBUG: $1"; 或使用 ngx_lua 記錄

最佳實踐建議

核心靜態化規則 → 主配置 location/rewrite (性能最高、可見性最好)
業務頻變 SEO 規則 → 受控目錄 .htaccess + CI/CD 自動 reload
密碼/IP/錯誤頁 → Nginx 原生指令 (無需 .htaccess)
遷移期雙寫 → 逐條驗證、灰度發布、監控錯誤率

合理利用 include 機制，在 Nginx 高性能架構下兼顧「配置靈活性」與「運維可控性」。