.htaccess 檔案是 Apache 的目錄層級設定檔,不是 PHP 檔案,但每個在 Apache 上運作的 PHP 專案都仰賴它來處理路由、重新導向和錯誤處理。由於 Apache 會在每次請求時、且在任何 PHP 程式碼執行之前,先讀取 .htaccess,因此單一個拼字錯誤或未跳脫的 regex 字元,就可能讓 PHP 網站離線、拋出 500 錯誤,或在不知情的情況下繞過團隊花了好幾週調校的 CMS 路由規則。Htaccess 產生器正是為了解決這個問題——它透過嚴格的輸入,產出刻意精簡、可審核的 Apache 2.4 .htaccess:固定一個正式的 HTTPS 主機、可選擇地停用目錄列表,並把找不到的頁面指向本機自訂的 404 路徑——而不是丟出一段可能不符合實際主機環境的複製貼上片段。因為產生器會在 RewriteCond 的 regex 中跳脫主機名稱的點號、總是建構 HTTPS 目標,並拒絕外部錯誤 URL,最常見的幾種 PHP 主機故障因此在建構階段就被排除,而不是靠運氣。
PHP 開發人員通常會碰到這個工作,是因為像 WordPress 這類 CMS、Laravel 這類框架,或自訂應用程式,都需要在 Apache 層級設定「乾淨的 URL」、強制 HTTPS,或一個友善的錯誤頁面。認為 .htaccess 是「PHP 檔案」的誤解,來自於 PHP 專案經常會在文件根目錄放一個 .htaccess,但實際上這個檔案是由 Apache 解析、在 PHP 執行前就執行,而且在 Nginx 或 IIS 上完全無用。理解這個差異,是寫出真正能在線上環境運作的規則的第一步。
.htaccess 檔案在 PHP 專案中的角色
Apache 會從被請求的目錄開始讀取 .htaccess,一路往上走到文件根目錄,在提供檔案或把控制權交給 PHP 之前,套用每一條符合的指令。這表示 .htaccess 檔案可以重寫 URL、設定環境變數、拒絕存取、重新導向請求,以及定義自訂錯誤文件——完全不需要動到 PHP 程式碼。對 PHP 網站來說,建立 .htaccess 最常見的原因包括:
- HTTPS 標準化。把每一個 HTTP 請求,以及每一個替代主機請求(例如頂級網域或 www 變體),都送往單一正式的 HTTPS 主機名稱。
- 乾淨的 URL。把像 /about 這種漂亮路徑,路由到 WordPress、Laravel、Symfony 中的 PHP 前端控制器,或自訂路由器。
- 自訂錯誤頁面。回傳帶有自家品牌的本機 404 文件,而不是 Apache 的預設回應。
- 安全與列表控制。停用自動的目錄索引、阻擋點開頭的隱藏檔,或以 IP 限制存取。
Htaccess 產生器專注於其中三項任務:固定主機的 HTTPS 重新導向、可選擇地停用目錄列表,以及本機自訂 404 路徑。它不會合成一整份伺服器設定,這樣的範圍是刻意的——規則的接觸面越小,就越容易審核,也就越不容易與主機或 CMS 已經強制執行的指令發生衝突。
為什麼複製貼上的 .htaccess 片段會搞壞 PHP 網站
大多數壞掉的 PHP .htaccess 檔案,都來自針對不同 Apache 版本、不同 CMS,或不同主機政策所撰寫的網誌文章。下列模式所造成的故障,比任何其他原因都多:
| 常見的片段模式 | 在一般 PHP 主機上為何會失敗 |
|---|---|
| RewriteCond %{HTTPS} off 搭配通用 regex | 讀取 Apache 的 mod_ssl 狀態。如果 TLS 代理先終止 HTTPS,Apache 看到的仍然是 HTTP,於是重新導向會陷入迴圈。 |
| 在共享 PHP 主機上使用 Options -Indexes | 需要 AllowOverride 包含 Options 類別;若沒有,Apache 會回傳 500 錯誤,而不是停用索引。 |
| ErrorDocument 404 https://example.com/404 | 產生器會拒絕外部 URL;外部目標會繞過 Apache 的本機錯誤處理,並可能掩蓋真正的故障。 |
| 未跳脫主機名稱的萬用字元 RewriteRule | 未跳脫的點會符合任何字元,因此 .example.com 會意外符合 xexampleacom。 |
產生器的價值不只是便利——而是「一致性」。每一份輸出都會在負向 HTTP_HOST 條件中跳脫主機名稱的點號、總是建構 HTTPS 目標,並拒絕外部錯誤 URL,藉此在建構階段就消除上述四種失效模式。如果需要更廣泛的規則集合,HTTPS 重新導向指南會更深入地說明正式重新導向的運作機制。
為 PHP 專案建立 .htaccess 檔案
請依照下列步驟,在允許你所選指令的 Apache 主機上,為 PHP 專案產出安全、可審核的 .htaccess。
- 確認 Apache 2.4 與 mod_rewrite。Apache 會讀取 .htaccess;如果沒有 mod_rewrite,HTTPS 區塊就無法運作;如果沒有 mod_ssl,HTTPS 條件則會永遠評估為 false。共享 PHP 主機幾乎都會包含這兩個模組,但在繼續之前,請先在 cPanel、Plesk 或主機商的說明文件中確認。
- 開啟 Htaccess 產生器,輸入確切的正式來源(origin)。輸入內容必須是公開網域的來源,不可包含認證資訊、連接埠、路徑、查詢字串或片段——例如 https://www.example.com。產生器會把這個值標準化為固定的 HTTPS 主機,並在 RewriteCond 的 regex 中跳脫主機名稱的點號。
- 只勾選主機允許的可選指令。只有當帳號的 AllowOverride 包含 Options 時,才勾選目錄列表選項;只有當本機檔案確實存在於所提供路徑時,才勾選自訂 404 選項。勾選了主機禁止的項目,會產生 500 錯誤,而不是優雅地退場。
- 輸入以斜線開頭的本機 404 路徑——例如 /404.php——並確認該檔案存在,且本身不會再觸發錯誤。產生器拒絕外部 URL 是有原因的:外部目標會把一個可恢復的 404,變成對第三方的依賴。
- 複製或下載產生的檔案。輸出會是單一、可審閱的 .htaccess,涵蓋 mod_rewrite、可選的 Options -Indexes,以及一條嚴格的 ErrorDocument 指令。在部署前請先讀過一遍——每一行都有用途,沒有隱藏行為。
- 備份既有的 .htaccess。從文件根目錄重新命名或下載現有的檔案。WordPress、Laravel 和大多數 CMS 內建前端控制器規則;盲目地覆蓋檔案,可能會停用漂亮 URL、破壞驗證流程,或略過快取標頭。
- 與 CMS、驗證及快取指令合併。如果 CMS 已經提供 RewriteEngine 區塊,請把新的 HTTPS 規則放在它上方,並保留前端控制器樣式不動。順序很重要:在同一個上下文內,Apache 會由上到下套用指令。
- 先在預備環境中上傳並執行檔案。瀏覽器和 CDN 會積極地快取 301 重新導向;錯誤的主機或路徑,可能會在快取生效期間把使用者釘在錯誤的 URL 上。預備環境讓你能在幾秒鐘內還原。
對使用 cPanel 管理的 PHP 網站來說,cPanel 檔案管理員指南說明了上傳的實際操作——不論如何送到伺服器,產生器的輸出都是同一份檔案。
產生的規則實際上做了什麼
理解輸出內容,日後除錯會更容易。HTTPS 區塊會啟用 mod_rewrite,檢查兩個條件——Apache 是否把該請求視為非 HTTPS,以及 Host 標頭是否與固定正式網域不同——然後發出單一 301 重新導向到正式主機,同時保留原始的 REQUEST_URI。因為目的地是寫死的,這條規則永遠不會從未受信任的 Host 值建構出外部重新導向,這也封閉了一個常見的開放重新導向攻擊面。
可選的 Options -Indexes 這一行,是在沒有 index 檔案時請 Apache 不要產生目錄列表。根據 Apache 的 mod_rewrite 介紹,目錄層級指令的行為與主要設定不同;如果 AllowOverride 沒有包含所需的類別,Apache 會拒絕該指令並回傳 500,而不是默默忽略。
可選的 ErrorDocument 這一行,只接受一條以斜線開頭的本機 URL 路徑,並拒絕外部 URL、空白、查詢字串和片段。Apache 的 自訂錯誤回應說明文件指出,本機目標可以讓錯誤回應留在網站內部,但目標必須存在,且本身不能觸發錯誤迴圈。
在 PHP 主機上安全地部署 .htaccess 檔案
請把產生的檔案當作正式環境的程式碼來看待。下列部署檢查清單,在共享 PHP 主機、託管 VPS,或自有的 Apache 執行個體上都一樣適用。
- 驗證 Apache 語法,使用 apachectl -t 或主機商提供的設定測試工具,再進行重新載入。語法上看似合理的 .htaccess,仍可能與主機政策不相容。
- 請求具代表性的 URL。測試純 HTTP、HTTPS、正式主機、替代主機(頂級網域、www、舊網域),以及一個已知不存在的路徑。每個都應該抵達預期目的地,或本機 404 文件。
- 關注錯誤紀錄。被禁止的指令、缺少的模組,以及 FileInfo 覆寫失敗,會以 500 回應或紀錄警告的形式浮現。若任何請求陷入迴圈或出現 500,請立即還原備份。
- 為快取做好規劃。301 回應會保存在瀏覽器與 CDN 中。如果正式主機送錯了,受影響的使用者會被重新導向,直到快取到期,或直到主動失效機制執行為止。
Htaccess 產生器不會連線到伺服器、偵測 Apache、檢查已啟用的模組、讀取 AllowOverride、驗證憑證涵蓋範圍,或執行 apachectl -t。要達到正式環境的正確性,仍然需要在 Apache 實際運作的 URL 上進行伺服器端設定驗證,以及真實的 HTTP 檢查。
When the Generated .htaccess Needs Adaptation
Three hosting architectures change how the file behaves, and each is worth knowing before deployment.
TLS terminates at a reverse proxy or load balancer. The HTTPS condition reads Apache's mod_ssl state. If a load balancer handles TLS and Apache receives plain HTTP, the redirect loops because Apache always thinks the request is non-HTTPS. The fix is to configure the redirect at the proxy or virtual host, or to adapt the rule to a trusted, overwritten proxy header only when the proxy path is controlled and the spoofing risk is understood.
AllowOverride restricts directive categories. Many shared PHP hosts permit FileInfo but not Options. If Options -Indexes triggers a 500, the host has told you, via that error, that the directive is not allowed in .htaccess. Either disable that option in the generator or ask the host to enable the relevant category.
Main Apache configuration is accessible. Official Apache guidance often recommends simpler virtual-host Redirect directives for canonical HTTP-to-HTTPS handling. With access to httpd.conf or the vhost file, the same outcome is achievable without .htaccess at all, which removes the per-request parsing cost and the per-directory override complexity entirely.
Common .htaccess Issues for PHP Applications
| Symptom | Likely Cause | Where to Check |
|---|---|---|
| 500 error after adding Options -Indexes | AllowOverride excludes Options | Host documentation, Apache error log |
| Redirect loop on HTTPS requests | TLS terminates upstream of Apache | Proxy/CDN configuration, mod_ssl state |
| Custom 404 page itself returns 500 | 404 target triggers an error or rewrite loop | Target file, server error log |
| WordPress pretty URLs stop working | Existing front-controller rule overwritten | Document root .htaccess, ordering |
| External 404 URL works in browser but not in crawlers | External URL accepted, local target required | ErrorDocument syntax, generator input |
If any of these appear after deploying the generator's output, restore the backup first, then investigate — never edit a live .htaccess that is causing outages. The file is small enough to keep a known-good copy in version control alongside the rest of the PHP project.
The Htaccess Generator is intentionally narrow — three directive families, strict inputs, and no hidden behavior — because most PHP .htaccess outages come from rules that look correct but were never validated in the environment where they run. Producing fewer, stricter rules, and validating them on staging before production, is the safest path from a copy-paste snippet to a working PHP site.