若要在 cPanel 中建立 .htaccess 檔案,請在 cPanel 控制台中開啟檔案管理員,導覽至網站文件根目錄(通常為 public_html),點選+檔案,將檔案命名為完全符合 .htaccess(含前導點),然後將產生或手寫的規則集儲存到其中。對於大多數共享方案,cPanel 主機執行的是 Apache,或是 Apache 相容的分支(例如 LiteSpeed),而 .htaccess 檔案是 Apache 在每次請求時讀取的每目錄設定檔。因為檔名以點開頭,cPanel 預設會隱藏它;您必須先在檔案管理員設定中啟用顯示隱藏檔案,圖示才會顯示。您也可以在 cPanel 外部於自己的電腦上建立檔案,再透過檔案管理員、FTP 或 SSH 上傳,但在檔案管理員內建立可將所有作業集中在一處,並讓您不離開瀏覽器即可編輯規則。Apache 僅在您的託管帳戶允許 AllowOverride 時才會套用 .htaccess 規則,許多共享主機會限制該政策。

how to create .htaccess file in cpanel
how to create .htaccess file in cpanel

.htaccess 檔案在 cPanel 中的位置

在 cPanel 中,.htaccess 檔案位於網站文件根目錄中:主要網域為 public_html,若是附加網域、子網域或子資料夾安裝則為其內部的子目錄。cPanel 的 Apache 組建會從請求進入的目錄讀取 .htaccess,並向上逐層檢查父目錄,直到找到一條規則或沒有更多路徑可檢查為止。在多數網站中,public_html 頂端的一個檔案即足夠;位於子資料夾內的另一個 .htaccess 只會覆寫該分支的規則。

因為檔名以點開頭,檔案管理員預設會隱藏它。點選右上角的齒輪圖示,選擇設定,然後勾選顯示隱藏檔案(dotfiles)。原本存在的 .htaccess(若有的話)就會像其他檔案一樣顯示出來。在您的 FTP 用戶端中也需要做同樣的設定:FileZilla、Transmit 和 Cyberduck 都會在其連線或檢視設定中提供「顯示隱藏檔案」的切換選項。對 SSH 使用者而言,ls -a 或 ls -la 即可從命令列顯示該檔案。

託管環境會控制該檔案被允許執行的動作。除非 AllowOverride 至少授予 FileInfo(用於 rewrite 規則)和 Limit(用於存取控制),否則 Apache 會忽略 .htaccess。共享主機通常允許 FileInfo 和 Limit,但少數主機會停用其中一項或兩者。如果某個指令產生500 Internal Server Error(500 內部伺服器錯誤)而非如預期運作,AllowOverride 是您透過主機說明文件或支援管道應首先檢查的項目。

使用 Htaccess Generator 產生規則

手寫一個能處理 HTTPS 正規化、目錄列表控制與自訂 404 頁面的 .htaccess 容易引入錯字,導致請求迴圈或網站離線。Htaccess Generator接受單一標準主機名稱加上可選旗標,然後產生一個簡短、可稽核的純文字 Apache 2.4 檔案。每一行都對應到一份有文件記載的 Apache 2.4 行為,檔案刻意保持簡短,而手動新增未經測試的規則正是此工具設計來防範的情境。

請完全依照訪客 URL 中應出現的形式輸入最終主機名稱,例如 https://www.example.com。輸入內容只能包含公開來源:不得包含認證資訊、連接埠、路徑、查詢字串或片段。產生器一律會建構 HTTPS 目標、為負向條件逸出主機名稱中的點,並組合一個保留原始 REQUEST_URI 的固定主機 301 RewriteRule。301 重新導向會告訴瀏覽器和搜尋引擎將新位置視為標準位置,但也會積極快取,這就是為何在上線前需要進行測試環境的驗證。

可選的核取方塊涵蓋另外兩項文件根目錄的考量。啟用停用目錄列表會新增一行 Options -Indexes,要求 Apache 在沒有索引文件時不要輸出檔案索引。啟用本機 404 路徑會新增一條指向以 / 開頭之路徑的 ErrorDocument 規則;外部 URL、查詢字串、片段及空白字元會被拒絕,因為它們可能產生迴圈或觸發主機無法控制的錯誤。若您的託管環境不允許這些指令,請將兩者皆取消勾選;該檔案仍可單獨用於 HTTPS 重新導向。

如何在 cPanel 檔案管理員中建立並上傳 .htaccess 檔案

  1. 透過 https://yourdomain.com:2083 或您提供者的自訂 URL 登入您的 cPanel 帳號,然後從「檔案」區段開啟檔案管理員
  2. 在右上角的設定齒輪中啟用顯示隱藏檔案(dotfiles),並在左側窗格中選擇文件根目錄(主要網域為 public_html)。
  3. 點選頂部工具列中的+檔案,在新檔案名稱欄位中輸入 .htaccess(含前導點),並確認位置為文件根目錄。
  4. 在清單中選取新檔案,點選編輯,然後貼上由 Htaccess Generator 產生的內容。Apache 會逐字解讀 dotfile 名稱,因此任何額外字元(例如 .htaccess.txt)都會破壞該檔案。
  5. 點選儲存變更,然後關閉編輯器。新檔案會在您儲存的當下寫入 public_html。
  6. 返回首頁目錄並點選重新載入,以確認圖示在儲存後仍列於清單中;部分 cPanel 版本會短暫快取目錄列表。

若 .htaccess 已存在,面板會在該列改為顯示編輯按鈕。請透過檔案管理員或程式碼編輯器外掛開啟它進行編輯,而非重新上傳,這樣單次寫入失敗才不會讓網站完全沒有檔案。同樣的程序也適用於附加網域或子網域:導覽至該網域的文件根目錄(cPanel 會將其置於 public_html 內部或作為同層目錄),並在該處依循相同步驟。

將新規則與現有 .htaccess 合併

以新檔案取代現有 .htaccess 是最快失去 CMS 路由、驗證、快取標頭、壓縮或 IP 存取控制的方法。在進行任何變更前請先備份目前檔案:開啟它、全選、將內容複製到一個名稱中帶有時間戳記的本機文字檔,並將該複本存放於帳戶外部(本機資料夾,而非 public_html 的子目錄)。

同時開啟兩個檔案。產生器的輸出僅涵蓋用於 HTTPS 重新導向的 mod_rewrite、Options -Indexes 與 ErrorDocument,因此每一區塊都必須與 CMS 原本產生的內容並存。多數前端控制器模式(WordPress、Joomla、Drupal、Ghost 的 proxy 區塊)會包圍在 if (mod_rewrite.c) 標記中,並以最終的 RewriteRule 作為結尾。請將標準主機名稱區塊插入到 CMS 區塊上方,讓重新導向優先執行,而不會被後續規則覆蓋。除非 CMS 指定了衝突的值,否則請將 Options 行保留在檔案最上方,並將 ErrorDocument 行置於兩個區塊之後,使錯誤處理位於串接的最下方。

成功合併後,請測試每一個頁面,而非僅僅首頁。固定連結、sitemap 請求、RSS 摘要、登入頁面與後台區域皆仰賴 rewrite 規則。若任何 URL 從原本回傳 200 變成回傳 404,請還原備份並重新檢查規則順序。如需更深入的逐步說明,了解如何將標準主機規則與 CMS 端路由合併,請參閱如何建立用於 HTTPS 重新導向的 .htaccess 檔案

三個可選指令實際的作用

對於查看每個區塊的功能及常見失效之處,一個簡短的表格比純文字敘述更實用。

指令 作用 可能失效的時機
RewriteEngine on + 標準化 301 在保留 REQUEST_URI 的前提下,將每個請求強制導向固定的 HTTPS 主機名稱 若 AllowOverride 未包含 FileInfo,則會出現 500 錯誤;若 Apache 位於 TLS 代理伺服器之後,則會產生重新導向迴圈
Options -Indexes 在沒有索引文件時,防止 Apache 列出目錄內容 若 AllowOverride 不允許 Options 指令,則會出現 500 錯誤
ErrorDocument 404 /path 將本機路徑作為 404 回應主體 若目標頁面本身觸發錯誤,會造成 404 迴圈;會忽略外部 URL

驗證 Apache 並測試每一個請求路徑

Apache 對於語法上看似合理的 .htaccess,會依託管它的伺服器設定而有截然不同的處理方式。當您擁有 root 或 sudo 權限時,請在 shell 執行 apachectl -t(或 service apache2 configtest);測試設定檔並不需要重新載入伺服器。多數 cPanel 共享帳號並未提供 shell,因此該處的 configtest 意味著向主機詢問,或在上傳至正式環境前先在本地 Apache 與測試伺服器上執行該檔案。

請在私密瀏覽視窗中對以下 URL 類型進行測試:

  • 首頁的 HTTP 版本:應 301 至 HTTPS。
  • 帶有查詢字串的內部 URL 之 HTTPS 版本:應在 HTTPS 上落在相同的路徑與查詢。
  • 替代主機(例如裸網域或不含 www 的變體):應 301 至標準主機。
  • 不存在的 URL,例如 /does-not-exist:應在本地提供設定的 404 頁面,而非託管預設頁面。
  • 資產路徑,例如 /wp-content/uploads/sample.jpg:應在不觸發任何規則的情況下正常解析。

若任何請求發生迴圈、回傳 500,或回傳錯誤的主機,請從先前建立的本機複本還原備份,並重新檢查合併結果。當某條規則不按文件說明運作時,Apache 的 mod_rewrite 介紹自訂錯誤回應文件是可靠的參考資料。

當網站位於 TLS 代理伺服器之後

許多 cPanel 式的部署會在 Apache 前面放置 Cloudflare、CDN 或負載平衡器。為直接連網的 Apache 站台所產生的 HTTPS 條件,依賴 mod_ssl 並假設 HTTPS 是以原生 TLS 送達 Apache。當代理伺服器終止 TLS 並轉送純 HTTP 時,該條件會永遠成立,導致每個請求都會經歷重新導向而陷入迴圈。

有三種可行的作法。最簡單的是直接在代理伺服器上發出 HTTPS 重新導向:Cloudflare 的 Edge Redirects、負載平衡器的頁面規則,或代理來源端的 Nginx 虛擬主機,都是合理的 301 強制執行位置。第二種作法是將 rewrite 條件調整為代理伺服器在每個請求上設定的、被覆寫的可信任標頭(例如 X-Forwarded-Proto),並檢查該值而非 mod_ssl。第三種作法是停用每目錄的 rewrite,並在主要 Apache 設定中設定虛擬主機的 Redirect;Apache 文件經常推薦此作法,因為它速度更快,且不受 .htaccess 的怪異行為影響。

無論採取哪種方式,重新導向的決定都應存在於實際看到使用者協定的層級。若位於其前方的層級會重寫請求的 scheme,則每目錄規則無法觸及該決定;因此,在以代理伺服器為後盾的 cPanel 站台中,從產生的 .htaccess 移除 HTTPS 區塊並在上游處理重新導向,通常是最簡潔的修正方式。

相關閱讀:htaccess 轉 Nginx:自動化轉換的限制