官方手冊 / CONFIG REFERENCE

Shadowrocket 設定檔欄位與規則分流指南

初次設定時,請先參閱快速入門,匯入現有訂閱或伺服器資料,並確認連線成功。本頁是供日後查閱的設定手冊:知道欄位名稱時,可依設定檔區段查看;連線正常但分流結果不如預期時,先檢查策略與匹配順序,再查看相關規則。裝置與取得方式請見下載指南。

01 / FILE STRUCTURE

設定檔結構與生效範圍

設定檔決定用戶端如何處理請求,伺服器資料則決定代理連線要連到哪裡。兩者可以分開變更:在 Home 切換現有伺服器,不代表已更換 Config 使用的規則檔;另存一份規則檔,也不會取代伺服器的驗證資料。開始編輯前,先確認目前連線實際使用哪台伺服器,以及 Global Routing 設為 Config 時實際使用哪份檔案。不要只因檔案清單中有熟悉的名稱,就認定該檔案正在生效。

依區段名稱辨別四類設定

設定區段用途適用情況
[General]共用參數,例如解析器設定多個無關網域同時受影響時
[Rule]依條件為請求選擇策略特定目標走錯連線路徑時
[Host]為特定主機名稱指定位址或解析方式少數主機名稱解析出非預期位址時
[URL Rewrite]依可見的 URL 匹配並執行改寫造訪舊位址卻被帶往其他頁面時

方括號內的名稱代表區段邊界。新增每一行之前,先往上找到最近的區段名稱,不要只看附近的文字。以 DOMAIN 開頭的行應放在 [Rule] 中;使用等號將主機名稱對應到位址的行則應放在 [Host] 中。例如,將規則貼到檔案末尾時,如果末尾仍位於 [Host] 區段,該行不會因拼寫正確就自動成為規則。若已有同名區段,請將項目加到原區段,不要在末尾另寫同名區段,試圖覆蓋前面的內容。

看懂最基本的設定檔架構

[General]
dns-server = system

[Rule]
DOMAIN,assets.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

這份架構範例只展示解析參數與規則的寫法,並非每份檔案都必須包含四個區段。共用參數以鍵和值表示;規則則以半形逗號分隔類型、匹配值與策略。範例中的資源主機使用 DIRECT,同一網域下其他符合條件的請求則使用 PROXY,未匹配的請求最後交由 DIRECT 處理。這只是閱讀範例,不是適用於所有網路的預設設定。尤其不要用它覆蓋現有檔案,否則原有的本機存取例外、服務群組與兜底行為可能一起改變。

編輯時請以目前正在使用的檔案為底稿,先另存一份易於辨識、日後可重新選用的副本,再一次只修改一個位置。從網頁複製程式碼後,確認方括號、等號與逗號仍是半形字元。網址列中的完整 URL 不能直接填入網域規則,規則行尾也不要附加說明文字。若設定檔由現有遠端來源管理,先確認更新是否會覆蓋本機編輯;使用獨立副本測試,才能分辨遠端更新與手動修改的影響。

確認要修改的是設定檔,還是連線資料

如果現有訂閱中的伺服器項目是空的、驗證失敗,或換用其他規則後仍無法連上同一台伺服器,請先檢查伺服器資料與基本連線。不要將訂閱連結寫進 [Rule],也不要為了讓代理規則生效而把伺服器位址填入 [Host]。反過來說,如果連線正常,同一台伺服器也能存取其他目標,只有某個網域用了非預期的策略,就從設定檔區段與規則順序查起。用戶端一次買斷不等於線路方案;本文假設使用者已有自己的訂閱或伺服器資料,不提供、販售或推薦節點或訂閱。

儲存後回到 Config 確認生效的檔案,再回到 Global Routing 確認目前選取的模式。若介面中有同名檔案,先使用容易區分的副本名稱,避免將兩次測試記在同一個名稱下。交接時請說明修改了哪個區段、希望哪些目標改變,以及哪些目標應維持原狀。只說「換了設定後就能開啟」不足以判斷修改是否有效:恢復也可能是網路切換,或舊連線剛好結束所致。

先記錄舊檔案與原設定,再確認新檔案是否生效。設定檔的儲存、選取與實際使用,是三種需要分別確認的狀態。

若只想了解設定檔的寫法,可進一步閱讀設定檔各區段說明。檢查設定時,優先使用已去除敏感資訊的單一區段摘錄。包含伺服器憑證、遠端設定網址、訂閱參數或真實內部主機名稱的原始檔案,請留在自己的裝置上,不要交由公開的文字比對服務處理。

02 / GENERAL

General:共用參數與 DNS 設定

多個原本無關的網域同時無法解析時,先檢查 [General] 與目前使用的網路,不要急著新增多條代理規則。網域解析的結果是位址,規則的結果是策略,兩者是不同的判斷。取得位址不代表該位址能建立連線;看到代理策略已選取,也不代表目標主機已正確解析。只有分別核對解析、策略與實際連線,才能判斷需要修改哪一層。

從 dns-server 確認解析基準

[General]
dns-server = system

範例中的 system 表示沿用系統提供的解析器,方便比較目前網路下系統原有的解析行為。它不是某個固定的公用解析服務。裝置在家用網路、公司網路與行動網路之間切換後,系統提供的解析器及可解析的名稱都可能不同。如果某個內部網域在公司網路可解析、在其他網路卻不行,先確認該名稱是否原本就只能透過內部解析器查詢,不要直接將這種差異歸因於規則。

編輯現有檔案時,找到實際存在的 dns-server 行,記下原值,再於副本中替換。不要新增兩個同名鍵值來做比較,也不要同時修改解析器、位址族設定與兜底策略。先測試一個平時穩定的一般網域,再測試一個出問題的網域;比較時使用相同網路與相同伺服器。如果基準測試也失敗,先檢查環境或共用設定。若只有問題網域解析失敗,還要檢查對應的 [Host] 項目、解析結果,以及是否存在特定網域規則。

分辨沒有結果、結果不同與連線失敗

沒有結果時,先確認輸入的名稱是否完整、目前網路能否連到解析服務,以及網路登入程序是否已完成。回傳結果不同不一定是故障:同一個網站可能因地理位置、電信業者或存取時段而回傳不同位址。正確的比較方式是記錄測試使用的網路、目標名稱與位址族,並重測同一目標,而不是把另一台裝置在不同連線下的結果當成固定答案。如果名稱已解析,但接著發生逾時或憑證錯誤,就應轉而檢查目標連線或服務名稱,不宜繼續更換解析設定。

IPv4 與 IPv6 的結果也要分開檢查。網站可能同時提供兩種位址,而終端裝置不一定每次都使用相同位址建立連線。如果某個 IPv4 位址存取正常,但使用網域名稱時偶爾失敗,先確認失敗的連線實際使用哪種位址。只看到 IPv6 結果,不足以判定問題出在 IPv6;還要確認同一目標是否確實透過該位址連線失敗,以及目前網路是否能連到該位址族。若必須暫時修改位址族相關設定來排查,請先保存原值,測試後再還原並找出長期原因。

處理解析與分流之間的交互情況

有些問題看似 DNS 設定不當,實際上是位址規則需要先取得位址才能判斷。只要有主機名稱,網域規則便可直接匹配;如果位址規則排在很前面,用戶端可能會先解析主機名稱,再判斷網段。若要保留明確的網域例外,先確認具體網域規則是否排在位址類規則之前,並留意位址規則是否附有 no-resolve。不要為了讓某條位址規則匹配,就把共用解析參數改成不適用於所有請求的值。

同樣地,修改解析器後沒有立即看到變化,不必反覆編輯檔案。舊 DNS 結果與已建立連線各自有不同的有效期間。先結束目前測試的工作階段,再送出新請求;必要時重新建立用戶端連線,並再次比較目前結果。如果只是從快取載入舊頁面,這次請求甚至沒有經過預期的網路流程。明確送出一次新請求,比反覆重新整理頁面更容易判斷結果。

解析器設定是用來處理特定解析問題,不是加快所有連線或取代線路的通用方法。測試結束時,留下足以說明結果的紀錄:使用哪份設定檔、解析器是由系統提供還是手動指定、在哪種網路下失敗,以及目標是沒有位址還是已有位址但無法連線。下次遇到類似情況時,便能先檢查同一層,不必重做所有修改。

目標名稱無法解析時,先檢查解析;名稱已有位址但無法存取時,再檢查該位址的策略、連線路徑與目標服務。不要把「能解析」當成「能存取」。

03 / DOMAIN MATCH

網域規則:精確、後綴與關鍵字

目標能以穩定的主機名稱表示時,優先選用範圍最小、最容易說明的規則。單一登入主機的例外使用 DOMAIN;同一網域及其子網域確實需要採用相同策略時,使用 DOMAIN-SUFFIX;只有在能接受跨網域誤匹配,而且找不到明確清單時,才考慮 DOMAIN-KEYWORD。選擇類型前,先找出請求實際使用的主機名稱,不要依頁面標題、服務名稱或瀏覽器顯示的簡稱猜測。

從完整網址擷取規則欄位

以 https://assets.example.com:443/manual/index.html 為例,網域規則使用的值是 assets.example.com。開頭的通訊協定、後面的連接埠、路徑和查詢參數都不屬於主機名稱。若只希望套用於某個目錄,無法單靠新增網域規則達成;相同主機名稱下的其他目錄也會受到相同網域策略影響。同樣地,後綴規則的匹配值直接寫 example.com,不必加上星號,也不需要附加路徑。

類型匹配值匹配範例不匹配範例
DOMAINassets.example.comassets.example.comimg.assets.example.com
DOMAIN-SUFFIXexample.comexample.com、img.example.comnotexample.com
DOMAIN-KEYWORDexampleassets.example.comassets.test.invalid

後綴匹配以網域層級為界,裸網域及其子網域都可能匹配,但不能只因另一個網域以相同字母結尾就將它納入。關鍵字匹配則檢查主機名稱是否包含該字串;例如 notexample.com 雖不屬於 example.com,仍包含 example。因此,排查時使用太短的關鍵字,容易連帶改變原本無關的服務。使用關鍵字前,先列出一個應匹配的目標,以及一個名稱相近但必須維持原狀的對照目標。

先寫例外,再寫分類規則

[Rule]
DOMAIN,assets.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

這段範例先處理精確主機,再套用於其他相同後綴的目標。對 assets.example.com 而言,兩條網域條件都可能成立;排在前面的精確規則已決定策略,後面的後綴規則不會再次處理。若將兩行對調,即使精確規則本身沒有寫錯,也無法達成例外效果。若檔案中已有維護者提供的廣泛規則,新增例外前要從檔案頂端開始檢查,不要只把新行放在 FINAL 上方。

一條後綴規則無法代表整個應用程式。單一頁面可能分別向主網站、登入介面、靜態資源與媒體服務發出請求,後幾項還可能使用完全不同的主機名稱。首頁能開啟,但登入或圖片異常時,請找出失敗的請求,再判斷該目標是否應與主網站採用相同策略。必要時為實際目標新增精確項目。不要只因幾個主機出現在同一頁面,就把規則擴大到它們共同包含的字詞或上層後綴。

看不到網域時,避免擴大規則範圍

使用者直接輸入位址、應用程式沿用既有連線,或用戶端無法識別目前連線的主機名稱時,可能看不到預期網域。此時把 DOMAIN 改成更廣泛的關鍵字,也無法補出主機名稱。先重新建立連線,確認請求是以名稱還是位址連線;如果服務確實以固定網段為目標,請改查位址規則。不要因為某個網域偶爾解析到共用位址,就永久將該位址視為這個網域。

維護一組網域規則時,應同時記錄「何時可以刪除」與「新增原因」。暫時性的排查例外在找到原因後就應撤回;長期例外則要定期確認主機名稱是否仍由相同服務使用。驗證結果至少應包含目標主機、同後綴的另一個主機,以及後綴以外的常用對照主機。如果三者都改變,先檢查是否修改了廣泛規則或兜底設定,不要繼續增加更多例外。

網域規則只處理主機名稱,不處理路徑,也不代表應用程式的所有網路請求。先找出確切的請求目標,再決定匹配範圍。

04 / ADDRESS & REQUEST

GEOIP、IP-CIDR 與 USER-AGENT

使用位址類規則前,先確認要匹配的是目標位址,而不是裝置送出請求時使用的本機位址。IP-CIDR 用於 IPv4 網段,IP-CIDR6 用於 IPv6 網段;GEOIP 則依據地理位置資料庫,為目標位址分類。三者都無法取代精確的網域識別。相對地,USER-AGENT 比對的是可見的請求識別字串,也不應視為可靠的應用程式身分。

以前綴長度限制位址範圍

[Rule]
IP-CIDR,192.0.2.10/32,DIRECT,no-resolve
IP-CIDR,192.0.2.0/24,PROXY,no-resolve
IP-CIDR6,2001:db8::/32,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

前兩行比較 IPv4 位址範圍:/32 只指定一個位址,/24 則涵蓋前三個欄位相同的一組位址,因此單一位址的例外應排在網段規則之前。第三行是 IPv6 前綴範例,不能放入 IPv4 規則;若只限定一個 IPv6 位址,請使用 /128。範例網段僅供文件說明語法與涵蓋範圍,不能用來測試實際服務。設定自己的網段時,先確認管理範圍,再一併寫入網路位址與前綴長度。

將 no-resolve 放在位址規則末尾,表示不要只為檢查這條規則而主動解析網域。目標本身是位址,或匹配流程已有可用位址時,仍可進行比對。它不會全域停用 DNS,也不會讓後續的 GEOIP 自動採用相同處理方式。如果目標仍只有主機名稱,附有此參數的位址條件可能無法判斷;接著仍會依序檢查後續規則。使用網域與使用位址存取同一服務時得到不同策略,不一定代表規則有誤。

將地理位置分類視為廣泛條件

GEOIP,CN,DIRECT 表示將地理位置資料庫分類為 CN 的目標位址交由 DIRECT 處理,不是匹配中文網站、帳號地區、裝置所在地或某類網域後綴。使用內容傳遞服務的網域可能回傳不同地區的位址;同一目標在不同網路下也可能得到不同結果。若要為特定穩定網域指定固定策略,請將網域規則排在地理位置分類之前,不要為了修正單一目標而調整整個區域的預設路徑。

排查地理位置規則時,記錄失敗連線實際使用的位址,而不只是手動查詢得到的結果。若回傳多個位址,本次連線不一定使用清單中的第一個。目標涵蓋多個位址範圍時,也不要把所有觀察到的位址拼成越來越大的網段,否則可能連同共用網段的其他網站一起納入。只有目標確實由自己管理且位址範圍相對穩定時,才適合長期使用網段作為識別條件。

請求識別規則的可見性限制

[Rule]
USER-AGENT,ExampleClient*,DIRECT
FINAL,PROXY

上方的虛構識別字串僅用於示範寫法:若用戶端能讀取相應的請求識別字串,以 ExampleClient 開頭的值便可匹配該項目。對一般加密連線而言,若用戶端只能看到連線目標,就不一定能讀取其中的 HTTP 請求標頭;有些請求本身也沒有可用的識別字串。即使識別字串可見,也可能隨應用程式更新或請求元件改變,或與其他應用程式相同。若需要穩定識別目標服務,優先使用明確的網域,不要為了讓這條規則生效而變更加密信任設定。

比較位址類規則與識別字串規則時,先確認目前請求提供哪些資訊,再檢查欄位是否寫得精確。若沒有可供比對的值,即使語法正確,也無法期待規則匹配。將網域例外、位址範圍與請求識別字串分別用於可驗證的情境,並記錄哪個條件先成立。若結果偶爾不同,找出一項可重複的差異,例如直接輸入位址時總能匹配、透過名稱存取時卻不匹配,再決定是否調整條件或順序。

網段不能取代網域,地理位置分類不能代表網站身分,請求識別字串也不能代表應用程式身分。條件範圍越廣,就越需要準備不應匹配的對照目標。

05 / POLICY & ORDER

策略、Global Routing 與匹配順序

判斷規則是否生效,第一步不是計算規則數量,而是確認 Global Routing。介面中的三種模式分別顯示為 Config、Proxy 和 Direct。若要測試目前規則檔中的網域例外、位址條件與兜底設定,應使用 Config。在另外兩種模式下看到存取結果改變,可作為診斷連線路徑的線索,但不能據此判定某一行 [Rule] 寫得正確或錯誤。

模式介面用詞排查用途
設定檔Config依所選設定檔的規則,判斷進入規則處理的請求
代理Proxy比較目標改走代理後是否可連線,不用於逐條測試規則
直連Direct比較目標透過目前網路直接存取的狀況

分開理解介面模式與規則動作

PROXY 是規則行的動作:將匹配的請求交由代理連線處理。它不會建立伺服器資料,也不保證目前伺服器能連到目標。DIRECT 讓請求透過目前網路直接存取目標,不代表可略過系統或目標服務的存取要求。REJECT 會停止轉送匹配的請求,可用於明確封鎖指定目標;頁面錯誤、逾時或資源遺失等表現會因應用程式而異,不能只看表面現象就判斷是否匹配拒絕規則。

介面中的 Proxy 與檔案裡的 PROXY 容易混淆。前者指定整體路由模式;後者只會在使用規則判斷時,成為某個匹配條件選出的動作。例如,若希望一般流量直連、特定服務走代理,不必將整體模式切換為 Proxy;應選擇 Config,並在檔案中加入代理條件。反過來說,若要暫時比較代理路徑是否可連線,也不必修改數十行規則,只要記下原本模式,測試完再還原即可。

依檔案順序逐步推演匹配結果

[Rule]
DOMAIN,updates.example.com,DIRECT
DOMAIN,telemetry.example.com,REJECT
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

依這段獨立範例閱讀:更新主機在第一行使用直連,另一個指定主機在第二行遭到拒絕,其餘同後綴目標在第三行使用代理。第四行只處理尚未被以上規則匹配、且可進行地理位置分類的請求。FINAL,PROXY 則接手所有未匹配前述條件的請求。遭拒絕的主機僅用來示範精確拒絕,不是可直接使用的清單。實際套用前,請確認拒絕後不會影響必要功能,並為該項目保留明確的復原方式。

這些規則會由最先匹配的項目決定去向,不會列出所有匹配項目再挑選最精確的一條。若將後綴規則移到兩條精確規則之前,例外就會失效;將地理位置規則提前,也可能先攔截原本要依網域處理的請求。檢查順序時,選定一個具體目標,從上往下逐行確認「這一行有足夠資訊可供判斷嗎?」以及「是否已匹配?」找到第一個匹配項目後就停止,不要用檔案後段另一條看似更合適的規則來解釋結果。

最後決定未列入規則的請求要前往何處

FINAL 不需要網域、地區或網段欄位,通常保留一條並放在規則末尾。FINAL,DIRECT 會讓未列入清單的請求直連,適合只讓明確指定的目標走代理;FINAL,PROXY 則讓其他請求使用代理路徑,實際結果取決於所選代理是否可用。判斷是否修改兜底設定時,要考慮一般辦公、家用裝置與臨時新增網域應如何連線,而不能只看目前出問題的單一網站。若經常靠修改兜底設定來解決單一網站問題,應回頭建立精確的例外規則。

測試一組策略時,至少準備三種目標:應匹配精確例外的目標、應被廣泛規則分類的目標,以及應套用兜底設定的目標。若有拒絕項目,再增加一個可安全失敗的請求。修改後必須重新建立測試連線,不能用已建立的連線推斷新策略。這種測試方式能同時發現兩類錯誤:新目標沒有如預期改變,以及原本不應受影響的目標也跟著改變。兩者都應在保留設定前處理。

06 / HOST

Host:指定主機名稱的解析結果

[Host] 適合處理範圍明確的名稱解析:已知某個主機名稱必須在受控環境中指向特定位址,而且不希望更換所有網域共用的解析器。它負責名稱與位址之間的對應。如果只是想讓某個名稱改走直連或代理,不需要固定位址,應修改 [Rule]。混用這兩種修改,會讓原本簡單的策略問題,變成解析、憑證與伺服器可達性三方面的排查。

固定位址與選擇策略是兩回事

[Host]
lab.example.com = 192.0.2.20

[Rule]
DOMAIN,lab.example.com,DIRECT
FINAL,PROXY

這段教學範例中,[Host] 行將指定名稱對應到文件用位址;[Rule] 行則讓這個確切名稱匹配直連。上下兩部分各自負責一件事:只保留前者,不會自動改用直連;只保留後者,也不會固定解析結果。若要在實際環境中採用這種結構,請使用自己管理的主機與可連線的真實位址,不要把文件用位址當成下載服務或診斷端點。

左側填寫主機名稱,不要填通訊協定、網址路徑或連接埠;右側填入符合情境的位址。為主機設定對應關係,不等於設定服務連接埠,也不會改變瀏覽器請求中的主機名稱。若新位址上沒有相應服務,或該連接埠沒有在監聽,即使解析成功,連線仍會失敗。如果同一位址承載多個網站,也要確認目標伺服器會依請求名稱選擇正確服務,而不只是確認它能對某個位址回傳任意頁面。

了解固定位址的限制

手動固定的對應關係不會隨原服務的 DNS 變更而自動更新。原本依賴多個位址輪替的服務,固定到其中一個位址後便會失去原有的切換能力;遷移完成後若忘記刪除項目,某台裝置可能持續連往舊伺服器。因此,長期項目應註明適用的網路、名稱與位址維護者。暫時性的遷移驗證則應明確設定撤回條件,不宜將測試時觀察到的某個公用位址寫成永久項目。

如果位址只在辦公室或實驗網路中可連線,切換到行動網路後失敗可能是預期結果。驗證時要記錄存取條件:裝置目前連接哪個網路、存取是否採用 DIRECT,以及目標位址是否對應實際監聽的連接埠。若請求經由代理路徑處理,也要考慮代理端能否連到相同位址,以及解析是在本機還是遠端完成。不要假設本機對應設定一定會改變遠端對該名稱的解析結果。

存取 HTTPS 時,名稱仍須與憑證相符。即使對應的位址可以連線,只要對端提供的是其他網站的憑證,就不能視為測試通過。直接開啟目標位址看到頁面,也不足以證明使用網域名稱存取會成功;兩次請求的主機名稱可能不同。遇到名稱不符時,先讓伺服器為測試網域提供正確的網站設定與憑證,不要把忽略身分驗證當成完成位址對應的步驟。

分別驗證修改前、修改後與復原後的結果

先記錄未修改時的解析與存取結果,再只新增一條對應,並使用原網域建立新連線。確認目標位址是否改變、策略是否維持不變,以及服務能否對原名稱正確回應。接著使用同一網域下不應受影響的另一個主機名稱進行對照,確認沒有順帶修改共用解析器或廣泛規則。若結果沒有改變,先確認選用的確實是修改後的檔案,再檢查是否仍在使用快取、舊連線或其他解析路徑。

復原時,請在副本中移除自己新增的位址對應,或重新選用舊檔案,再送出新請求,確認位址是否回到原本的解析路徑。不要只刪除搭配使用的直連規則,否則固定位址仍會保留,之後的存取可能繼續連到舊伺服器。也不要只確認編輯器中已看不到該行;真正的復原結果,是新請求重新依預期解析。測試完成前應保留對照紀錄,但不要公開真實的內部名稱與位址。

用 [Host] 管理位址,用 [Rule] 管理連線去向。驗證固定位址時,務必使用原網域送出新請求,並保留可供復原的設定檔副本。

07 / URL REWRITE

URL Rewrite:請求網址改寫與重新導向

[URL Rewrite] 可依據可見的 URL 執行改寫,例如將自己管理的測試網站上舊版說明頁,導向同一網站的新頁面。它不是另一種規則策略寫法。[Rule] 用來決定目前目標採用哪種連線路徑;[URL Rewrite] 則處理匹配到的請求網址如何變更。若只是想讓某個網域走代理,應新增規則而非重新導向,否則存取頁面與請求流程也會改變。

將匹配範圍縮小至特定通訊協定、主機與路徑

[URL Rewrite]
^http://docs\.example\.com/old-help$ http://docs.example.com/help 302

此行以空格分隔匹配運算式、目標 URL 與重新導向狀態。開頭的 ^ 和結尾的 $ 用來限定整個網址;主機名稱中的 \. 代表字面上的句點,而非任意字元。此範例只匹配不含查詢參數、結尾沒有斜線的舊頁面;不匹配更深層的路徑,也不會匹配目標頁面本身。明確寫出這些邊界,比使用一條匹配所有相似字串的運算式更容易驗證與撤回。

此範例使用一般 HTTP,說明用戶端能看到完整網址時的行為,適合在自己控制的測試環境中驗證。不要因此將實際服務從 HTTPS 改成 HTTP,也不要為了套用範例而降低系統的憑證驗證要求。只能識別 HTTPS 連線的主機,不代表也能識別完整路徑與查詢參數。若是自己維護的加密網站,正式的網址搬遷應優先由伺服器回傳正確的重新導向,讓不同用戶端都能得到一致結果。

確認改寫會觸發新的請求

在這個 302 範例中,應用程式若接受重新導向,就會依照新網址再送出一次請求。新請求的目標必須能獨立連線,適用的策略也應針對新目標確認。舊網址匹配成功,不代表新頁面已成功載入。測試時請分別記錄兩項結果:舊請求是否收到預期的重新導向,以及新網址的請求是否取得預期內容。如果第二個步驟失敗,應檢查新目標的解析與策略,而非繼續放寬舊網址的運算式。

說明頁的重新導向不能直接套用於登入、表單提交,或需要維持方法與請求內容的介面。應用程式跟隨 302 時,可能改用不同的請求方法,也可能不轉送原有請求內容。尤其不要拿含有登入狀態、憑證或私人查詢欄位的真實請求來測試。即使目標網域不變,修改路徑也可能讓請求送到用途不同的處理程序。使用不含敏感參數、只讀取靜態內容的頁面進行對照,可避免這些副作用干擾驗證。

檢查重複匹配、迴圈與快取

先在沒有任何改寫規則時,分別存取舊頁面與新頁面,確認回應來自哪裡。新增單一規則後,用舊網址驗證正向匹配,再以新網址和相鄰路徑驗證不匹配。如果新網址也匹配相同運算式,或網站本身又將新網址導回舊網址,就會形成迴圈。此時應縮小匹配範圍或撤回改寫,不要再新增第三條重新導向來掩蓋問題。也要檢查是否有其他改寫同時涵蓋這兩個網址;逐條停用測試,比同時修改多個運算式更容易找出原因。

刪除規則後若仍看到跳轉,先比較一次新請求,再判斷是用戶端仍使用舊設定、應用程式沿用先前的回應,還是伺服器自行重新導向。網址列最後停留的位置無法顯示中間經過幾次跳轉。如果目標在第一次測試前就會自行跳轉,應從單次請求收到的回應判斷新增規則是否生效,不要只因最後顯示相同頁面就下結論。若沒有可用的診斷資訊,可先移除改寫、重新建立連線,再分別測試兩個網址。

只保留能明確說明作用範圍的改寫項目。每項都應能回答:為何需要保留舊網址、哪些請求不能改、由誰維護新網址,以及何時可以撤回。不要把改寫設定當成正式服務搬遷的唯一方法。若多人與多台裝置都必須得到相同結果,由伺服器明確回應,比各裝置各自維護本機改寫更容易核對。

先用一條規則與兩個可控網址進行比較。若需要比對的資訊是無法看見的加密路徑,擴大運算式也無法解決匹配問題。

08 / VERIFY & RESTORE

設定驗證、故障排查與復原

設定排查的目的不是讓某次重新整理碰巧成功,而是確認哪項修改造成可重複的變化。先選定一個可重複送出的請求,記下預期主機、策略與結果,再記錄目前使用的網路、設定檔及伺服器。盡量在同一台裝置上進行比較,不要同時切換無線網路、連線模式或訂閱中的伺服器。無法控制的條件也應記錄,例如測試時裝置剛從無線網路切換到行動網路。

用四個步驟辨別故障所在層級

  1. 連線:確認 Home 中的連線狀態與目前選用的伺服器。可使用現有資料執行 Connectivity Test;測試通過只代表該項測試成功,不代表所有服務目標都能連線。
  2. 設定:從 Config 確認實際使用的檔案,再從 Global Routing 確認目前是否處於 Config。送出一次新請求後,觀察目標是否進入預期的規則處理流程。
  3. 解析:需要依位址判斷時,比較目前網路實際使用的位址與位址族;若目標連可用位址都沒有,先不要新增位址規則。
  4. 服務:檢查代理或直連策略是否符合預期,並確認存取失敗發生在建立連線、驗證憑證,還是服務回應之後。

同一個請求在 Proxy 下成功、在 Config 下失敗時,應優先檢查 Config 中是否有更早的規則套用不同策略,或兜底路徑是否與預期不符。如果兩種模式下都失敗,先檢查共用的伺服器、目標與網路條件;若 Direct 可成功,至少可作為直連結果的對照,但仍不能只憑這點判定是哪條規則出錯。完成模式比較後,請切回原設定,避免將診斷操作留作日常設定。

檢查未匹配與規則遮蔽

[Rule]
DOMAIN,editor.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

可依這段範例準備三種驗證目標。第一種是指定例外,預期使用直連;第二種是同後綴的其他主機,預期使用代理;第三種是不屬於該後綴、也不會匹配其他條件的主機,預期套用兜底設定。範例名稱只用來說明規則關係;實際測試時,請換成符合這些條件且確認可連線的目標。第一種失敗時,回到檔案頂端尋找更早匹配的項目;第二種失敗時,確認目標是否確實屬於相同後綴;第三種結果改變時,檢查是否誤改兜底設定或其他共用參數。

有兩種情況容易被誤判為未匹配。第一種是沿用修改前已建立的連線;即使檔案正確,新規則也沒有機會處理舊連線。第二種是主要頁面能開啟,但失敗的附屬請求使用了完全不同的主機名稱。前者應重新建立測試連線,後者則應找出實際失敗的目標。不要只為了讓介面不再顯示錯誤,就替整組服務更換策略。若需檢查一段請求紀錄,只摘錄足以辨別規則類型的內容,並先移除訂閱查詢參數、驗證欄位與私人位址。

依症狀撤回最小範圍的修改

若只有一個目標受影響,先移除最後新增的精確規則,再測試同一請求。若多個原本正常的目標同時出問題,優先還原最近修改的廣泛規則、FINAL 或 [General] 參數。若修改涉及多個區段,而且沒有明確紀錄,就直接重新選用已知可正常運作的舊檔案。還原舊檔案後,也要確認路由模式與伺服器;若仍保留對照測試時使用的模式,就算檔案已復原,也無法重現原本狀態。

有些變化並非由檔案觸發。例如,切換網路後,用戶端可能依據 On Demand 條件重新建立連線;現有遠端設定檔更新,也可能取代先前用於測試的內容。若問題只在切換時發生,先固定使用同一個網路完成一次比較,再分別檢查 On Demand 條件與遠端設定檔是否有變化。如需了解連線觸發與背景行為,請參閱On Demand 與背景耗電說明,不要用新增分流規則來補償尚未查明的連線重建問題。

最後留下的紀錄不必完整抄寫設定檔,但至少要能回答四件事:修改了哪裡、哪個目標改變、哪個對照目標維持原狀,以及如何復原。若還原舊設定後仍無法存取,請停止繼續疊加修改,回頭檢查伺服器資料、裝置連線狀態與目標服務本身。可從常見問題中的無法連線排查繼續確認;若要重新完成新增資料、選擇模式與驗證連線的整個流程,請依照快速入門的步驟操作。

驗收以新請求為準:該改變的目標已經改變,不應改變的目標維持原狀,而且舊檔案與原有設定仍可復原。