官方手冊 · 設定欄位

Shadowrocket
設定欄位與規則參考

先確認目前生效的設定檔,再核對規則條件、排列順序與最終策略。本頁依檔案結構編排,適合搭配現有設定逐項查閱。

第一次使用,請先閱讀快速入門教學,完成現有訂閱匯入與首次連線;本頁說明設定檔的運作方式,不重複介紹初次操作流程。需要取得用戶端,請前往全平台下載頁。

[General] [Rule] [Host] [URL Rewrite]

01 · 設定檔結構與生效範圍

Shadowrocket 設定檔以方括號標示段落,各段落負責不同類型的設定。閱讀檔案時,先看段落名稱,再看段落內的語法,不要把所有包含逗號的文字都當成規則。常見結構包括處理基本行為的 [General]、決定連線去向的 [Rule]、指定網域與 IP 位址對應的 [Host],以及改寫符合條件網址的 [URL Rewrite]。段落之間有明確界線;即使單字拼寫正確,內容放錯段落,也不會有預期中的效果。

從最精簡的檔案開始閱讀

以下片段用來說明結構,不是適用於所有網路環境的完整設定。範例保留系統相關的基本行為,再列出一項網域條件和一條最終規則。example.com 是文件中的示例網域,請替換成有權使用且需要測試的目標。規則中的 PROXY 仍須搭配用戶端中現有且可用的代理選項;單獨複製這段文字,無法取代伺服器參數、驗證資訊或訂閱匯入。

[General]
bypass-system = true
dns-server = system

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

設定檔、伺服器清單與目前連線狀態,是三個不同層次。伺服器清單保存連線所需資訊,設定檔說明流量如何處理,連線開關則決定系統流量是否進入目前的處理流程。檔案出現在清單中,不代表已經選用;選了某個檔案,也不代表目前流量一定會依其中的規則分流。檢查時還要確認 Global Routing(全域路由)目前的模式,尤其要留意是否曾暫時切換至 Proxy 或 Direct,之後忘了切回。

開啟、編輯與切換是不同步驟

在 Config(設定檔入口)中,先確認目前使用的檔案,再開啟編輯或詳細資訊頁面。不同平台的入口位置可能不同,請以目前 App 內顯示的文字為準。修改前先保留原檔副本;儲存後確認沒有解析錯誤,再核對目前選取的項目。若正在排查問題,建議只保留一份明確的測試副本作為本次檢查對象,避免同名檔案、遠端檔案與本機副本混在一起,最後編輯的並非正在使用的檔案。

段落主要用途查閱重點
[General]基本行為與解析設定欄位名稱、設定值與適用條件
[Rule]依連線條件選擇策略條件範圍、排列位置、最終策略
[Host]固定網域與 IP 位址對應位址有效性與解析覆蓋範圍
[URL Rewrite]比對並改寫網址比對式、目標網址、可見的連線範圍

檔案中的空白行主要用來區隔內容,並不會讓前後兩條規則變成獨立流程。相較之下,段落標題會改變後續內容的解讀方式。手動合併檔案時,最容易出錯的是只複製規則內容,卻漏掉所屬段落;或是把第二份檔案的基本欄位直接接在規則末尾。較穩妥的做法是依段落整合並逐段比較,而不是把兩份完整檔案直接首尾相接。重複欄位也不應靠猜測處理;應先消除歧義,再檢查儲存結果。

從網頁或聊天內容複製設定時,請留意全形逗號、彎引號、不可見空格,以及因自動換行而拆開的長行。規則欄位之間使用英文逗號,鍵值欄位通常使用等號;畫面上的換行不一定代表檔案真的換行,但貼上時可能會插入換行。若發現一條規則被拆成兩段不完整的文字,請回到純文字編輯畫面核對,不要試圖增加更多規則來補救語法問題。

查閱本頁的順序可依故障範圍調整:檔案無法儲存,先檢查結構和語法;連線走錯策略,先檢查模式與順序;網域無法解析,改查基本欄位和位址對應;只有特定網址轉址異常,再檢查改寫設定。如此可分別判斷「檔案能否讀取」、「規則能否比對」及「比對後能否連線」,避免把伺服器無法使用誤認為規則格式錯誤。

02 · General、DNS 與基本行為

[General] 用來設定基本行為,不是依網域逐一選擇代理。閱讀這個段落時,應先確認:欄位會影響哪些連線、是否會改變解析方式,以及是否與系統服務有關。不要因為另一份設定列出很多欄位,就認為欄位越多越完整。不熟悉的設定值會增加排查範圍;只保留必要設定,並且能說明每個設定值的檔案,通常更容易驗證與維護。

認識範例中的兩個欄位

bypass-system = true 用來啟用系統相關流量的略過行為,但不能因此推論「所有直連規則都不用設定」,也不代表關閉系統代理。實際涵蓋哪些系統流量,應配合目前的 App 設定與執行環境確認。dns-server = system 表示使用系統 DNS 作為解析來源;這不保證解析結果固定,也不代表每種網路環境都會得到相同答案。

[General]
bypass-system = true
dns-server = system

網域解析與路由選擇彼此相關,但並非同一件事。網域條件可依連線帶有或用戶端辨識到的網域進行判斷;位址條件則需要可供比對的目標 IP 位址。有些連線一開始只有網域,有些直接連往 IP 位址,另一些則可能因快取而沿用先前結果。因此,僅憑「在瀏覽器輸入的是網域」,不足以判定每個步驟都會重新解析,更不能證明這次連線一定會使用某一台特定 DNS 伺服器。

先分辨解析失敗與連線失敗

遇到目標無法開啟時,先確認問題發生在哪一層。如果網域沒有解析出可用位址,應檢查目前網路的解析能力、系統 DNS 與固定對應;如果已有位址但無法建立連線,則應檢查策略、代理伺服器和目標服務。單純將最終策略從直連改為代理,無法保證修正錯誤的固定位址。同樣地,網域成功解析只代表解析步驟有結果,不代表目前的連線出口能連上該位址。

切換 Wi-Fi 與行動網路後,系統使用的 DNS、區域網路位址和可連線範圍都可能改變。公司內部網域可能只有在特定網路中才能解析;家用裝置的位址可能由路由器指派;公共網站也可能因網路位置不同而回傳不同的服務位址。排查時先固定網路,再測試一個明確目標。如果同時切換網路、更換 DNS、更新訂閱並修改規則,即使恢復連線,也很難判斷是哪項變更發揮作用。

不要把不同來源的 DNS 設定直接合併。不同欄位可能分別控制解析來源、回退條件或特定情況下的處理方式;表面上看起來都是「加一個位址」,實際上卻可能改變請求順序與失敗路徑。本頁只提供方便重現的基本片段;需要調整更細緻的行為時,請先查閱目前用戶端提供的欄位說明,再針對單一目標進行對照測試。若沒有明確問題,不必為了增加欄位數量而更改解析方式。

快取與重複測試的注意事項

修改解析相關設定後,舊連線和快取可能會持續影響短時間內的觀察結果。請結束相關連線,必要時重新建立用戶端連線,並重新發起存取;若 App 提供相關紀錄或快取操作,請以實際介面為準。不要因為重新整理後仍顯示舊頁面,就認定規則沒有儲存。瀏覽器內容快取、App 長連線與網域解析快取屬於不同層次,清除其中一項不一定會影響其他項目。

記錄基本設定時,請寫明目前的網路、系統是否使用其他網路設定,以及測試目標是網域還是直接輸入 IP 位址。使用公司網路或受管理裝置時,不要為了驗證規則而自行移除組織要求的設定。先建立可還原的測試條件,再逐項定位問題。如果同一份檔案在兩種網路中的表現不同,通常代表環境條件改變,而不是檔案內容自行變動。

保留欄位的標準是:用途清楚、能在目前環境驗證,並且有還原方式。問題修正後,移除臨時加入且用途不明的設定值,保留原始副本和簡短的修改說明。如果問題集中在單一目標,可繼續檢查下文的網域條件和位址條件;如果所有目標都失敗,則應一併檢查連線入口與現有伺服器狀態,避免在規則段落中重複加入相同條件。

03 · Global Routing 與三種策略

Global Routing(全域路由)決定整體的處理模式;規則末尾的策略則決定命中該規則後的連線去向。兩者名稱相近,但所屬層次不同。介面中的 Config(設定)、Proxy(代理)、Direct(直連)用來選擇整體模式;設定檔中的 PROXY、DIRECT、REJECT 則是規則策略。判斷設定是否生效,必須同時檢查這兩個層次,不能只確認其中一項。

先確認模式,再分析規則

日常需要依規則分流時,請使用 Config,並確認已選取正確的設定檔。在 Proxy 模式下,流量會依代理模式處理,不能以此時的結果驗證規則段中的直連條件是否生效;在 Direct 模式下,也不能因為連線成功,就斷定代理伺服器正常。這裡說明的是整體分流方式;系統保留行為、可見的連線範圍等條件,仍可能影響實際請求,不應將模式名稱理解為涵蓋所有系統通訊的保證。

介面模式主要用途驗證時請留意
Config(設定)依目前設定檔的規則分流檢查設定檔、規則順序和最終命中項目
Proxy(代理)暫時檢查代理連線路徑不能用來證明規則中的直連條件有效
Direct(直連)暫時檢查直連路徑連線成功不代表代理伺服器可用

規則中的三種策略各自負責什麼

PROXY 表示交由目前選取的代理處理,不代表設定檔會自動指定一台永遠可用的伺服器。伺服器故障、驗證資訊不符或協定參數錯誤時,即使命中這項策略仍可能連線失敗。DIRECT 表示透過目前網路直接連線,仍取決於本機解析、路由和目標服務。REJECT 表示拒絕符合條件的流量,並非「選擇速度較快的線路」,也不應在無法解釋錯誤時當成通用修正方式。

[Rule]
DOMAIN,blocked.example.com,REJECT
DOMAIN,local.example.com,DIRECT
DOMAIN,service.example.com,PROXY
FINAL,DIRECT

上述拒絕規則只會比對範例主機;直連與代理規則也各自指向明確主機。檔案不會測量速度,也不會因代理連線失敗,就自行將這項請求改為直連。若需要特定的回退行為,應確認目前用戶端是否提供相應功能並明確設定,不要將「寫了多個策略名稱」誤認為具備自動容錯。一條規則末尾的策略,通常只表示符合該條件時要採取的處理方式。

應區分連線測試與實際服務請求。某項 Connectivity Test(連線測試)有結果,只能說明在該測試條件下取得了結果,不能取代對目標網站的實際請求。目標可能需要不同連接埠、不同傳輸能力,或依賴多個相關網域。排查時先確認現有伺服器基本可用,再驗證特定目標是否命中預期策略,最後確認實際服務流程是否完整;這三個步驟不能互相取代。

將暫時的排查模式切回設定模式

暫時切換到代理模式後,目標恢復連線,表示代理路徑值得進一步檢查,但還無法判定是哪條規則有問題。切回設定模式,查看失敗請求原本命中了哪項規則;如果命中直連,再分析是否缺少精確規則、被較寬的條件提前比對,或用戶端未能辨識網域。不要為了單一目標長期停留在暫時模式,卻以為其他 App 仍會依照設定檔中的例外條件運作。

在直連模式下成功、代理模式下失敗,也不能直接證明所有規則都應改為直連。可能是目前的代理伺服器無法使用、目標不接受該出口,或伺服器參數與自己的資訊不符。應保持目標和網路不變,每次只更動一個變數,並記錄每次測試的模式與結果。若要進一步了解三種模式的操作方式,可閱讀Global Routing 三種模式的差異。

維護設定時,建議為每項策略選擇寫下清楚的目的:這台主機為何要走代理、這個網段為何要直連、這個目標為何要拒絕。沒有用途說明的廣泛拒絕規則尤其需要謹慎,因為它可能影響登入、更新或資源載入。不要只確認首頁能否顯示,也應測試日常必要操作,再決定保留或撤回策略變更。

04 · DOMAIN 系列網域規則

網域規則適合用來說明「哪個主機要走哪條連線路徑」,通常比隨手收集幾個目標 IP 位址更容易理解。常見的三種條件是 DOMAIN、DOMAIN-SUFFIX 和 DOMAIN-KEYWORD,分別用來比對指定主機、網域及其子網域範圍,以及網域中包含的字串。選擇時先確認適用範圍,再採用範圍最小且足夠的條件;不要因為關鍵字寫法簡短,就預設使用它。

精確比對與後綴比對

DOMAIN 只比對指定的主機名稱。為 api.example.com 設定精確規則,不代表也會涵蓋 example.com 或該服務的圖片主機。DOMAIN-SUFFIX 用來涵蓋網域本身及其子網域,例如 example.com 與 api.example.com。後綴規則依網域邊界判斷,不是比對任意相同結尾字串,因此不能將名稱相似、但不屬於該網域的主機視為同一範圍。

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

這組規則先為 API 主機設定代理例外,再讓相同網域範圍內的其他目標直連。這示範的是「精確例外在前、較廣泛條件在後」,並非自動依精確程度排序。若兩行對調,API 主機會先命中後綴條件,前面的例外規則就沒有機會生效。閱讀檔案時,應依實際行序逐條推演,不要自行假設較具體的規則會自動排在前面。

使用關鍵字比對時應控制範圍

DOMAIN-KEYWORD 會檢查網域是否包含指定字串,不表示網域之間具有從屬關係。關鍵字 example 的範圍比後綴 example.com 更廣,可能比對到多個不同網域。只有在確認需要這種廣泛比對時才適合使用;不應長期以它取代「尚未找到完整網域」的暫時做法。關鍵字太短,誤比對機率和排查成本都會增加。

規則比對範圍示意常見範圍限制
DOMAIN,api.example.com,PROXY指定 API 主機不會自動涵蓋同網域的其他主機
DOMAIN-SUFFIX,example.com,DIRECT該網域及其子網域不代表比對任意相似字串
DOMAIN-KEYWORD,example,PROXY網域中包含指定字串可能涵蓋無關網域

網域條件中應填寫主機名稱,不要填入完整網址。協定前綴、連接埠、路徑和查詢參數都不屬於網域的一部分;若將完整網址貼到後綴欄位,通常就不是在比對預期的對象。一般網域條件無法區分網址路徑。同一主機上的登入頁面與圖片路徑,可能都會命中同一條網域規則;需要依網址處理時,應先了解下文說明的改寫範圍,不要在網域後面加上斜線。

一個頁面可能會連線到多個網域

主頁可以開啟,但登入失敗,不一定是主網域規則寫錯。頁面可能還會連線至驗證 API、靜態資源或其他服務網域。請從實際失敗的請求著手,確認主機名稱後,再決定是否新增獨立規則。不要為了補齊一個服務流程,就把所有包含品牌字詞的網域都設成相同策略;名稱相似不代表用途相同,也不表示需要相同的連線出口。

登入、付款等連續流程,建議在同一輪測試中檢查入口、轉址、回呼和必要資源,不要只重新整理首頁。如果某個 API 需要代理而主頁使用直連,先保留這項精確差異,再觀察實際結果。跨網域請求失敗也可能與伺服器權限、帳號狀態或 App 快取有關;規則只決定連線路徑,無法修正錯誤的驗證資訊,也不能改變目標服務本身的業務限制。

重複網域規則應依第一個命中位置判斷。兩條完全相同但策略不同的條件,後者不會成為「備用」規則;若一條後綴規則的範圍包含另一條,也要考慮兩者的涵蓋關係。整理檔案時,先找相同主機,再檢查父網域與子網域,最後確認關鍵字和其他條件是否重疊。刪除重複內容前先保留副本,並確認留下的規則位置正確,不要只依文字內容去重。

若網域規則看似沒有作用,先確認目標確實以該主機發起新的連線,再查看請求紀錄中是否能辨識出網域。直接連線至 IP 位址、沿用舊連線或經過不同轉址,都可能讓實際觀察對象與預期不同。確認請求對象和比對條件一致後,再繼續檢查規則順序。這樣能避免針對錯誤主機反覆新增意思相近的規則,卻始終沒有處理真正失敗的請求。

05 · IP-CIDR、GEOIP 與 USER-AGENT

位址規則處理的是目標 IP 位址,而不是網頁名稱。IP-CIDR 以網段表示一組 IPv4 位址,IP-CIDR6 適用於 IPv6 位址範圍,GEOIP 則依位址歸屬資料分類。這些規則可以和網域規則同時使用,但判斷依據不同。先確認請求有哪些可用資訊,再選擇適當條件;不能只憑網域後綴或頁面語言,就推斷它會命中某項位址歸屬條件。

網段代表一組 IP 位址

192.168.0.0/16 代表對應的私有 IP 位址範圍,不等於「本機目前連線的所有區域網路」。家用網路也可能使用其他私有網段,公司網路則可能採用不同規劃。為區域網路服務設定規則前,請先確認實際目標位址和網路範圍,不要直接把網路上看到的網段套用到目前環境。規則允許某種連線方式,也不會自動建立網路路由;裝置不在可連線的網路中時,設定為直連仍可能無法連線。

[Rule]
IP-CIDR,192.168.0.0/16,DIRECT
IP-CIDR,10.0.0.0/8,DIRECT
IP-CIDR6,fc00::/7,DIRECT
GEOIP,CN,DIRECT
FINAL,PROXY

範例同時展示私有位址範圍、IPv6 本機位址範圍和位址歸屬條件,但不代表所有使用者都應照原樣啟用。前綴長度越大,涵蓋的位址範圍通常越小;單一 IPv4 位址可用 /32 表示,單一 IPv6 位址則可用 /128 表示。編輯時應確認 IP 位址和遮罩屬於相同位址類型,避免在 IPv4 規則中填入 IPv6 位址,或誤把一般連接埠號碼當成前綴長度。

解析選項不等於效能開關

位址規則可能需要先解析網域,才能比對 IP 位址。支援相關選項的規則可加上 no-resolve,表示不要只為了比對這項條件而主動觸發解析;這不代表「禁止整台裝置使用 DNS」。如果請求已帶有 IP 位址,仍可能符合位址條件。如果請求只有網域而沒有可用位址,帶有此選項的規則可能無法命中,接著會繼續檢查其他規則。是否加入此選項,應依預期行為決定。

[Rule]
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
FINAL,PROXY

GEOIP,CN,DIRECT 表示依位址歸屬進行分類,不是比對網域中的文字,也不表示所有相關網站都只使用這類位址。內容傳遞、服務遷移與資料更新,都可能讓實際結果和預期不同。如果某項服務必須穩定採用指定策略,通常應先確認其具體網域,並設定明確規則,不要只依賴範圍較廣的分類。分類資料只是判斷依據之一,不能證明服務的實際歸屬。

USER-AGENT 的可見範圍限制

USER-AGENT 會依請求中的對應欄位比對用戶端識別資訊,並不等同於依作業系統的 App 程序分流。多個 App 可能使用相同識別資訊,同一個 App 也可能依請求類型使用不同內容。更重要的是,一般加密連線不會自動公開其中的請求欄位,因此不能假設填入 App 名稱就能辨識該 App 的所有連線。使用這類條件前,必須先確認目前請求確實提供可供比對的資訊。

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

這裡的識別資訊只是比對模式範例,不對應任何真實 App 的固定識別內容。測試時,請從有權檢視的請求中確認實際內容,並核對大小寫、空格及萬用字元範圍。不要把瀏覽器顯示名稱當成完整的請求欄位,也不要靠猜測 App 名稱來堆疊規則。若無法確認欄位是否可見,應優先使用已驗證的網域條件,而不是把沒有命中解讀為代理伺服器故障。

位址、網域和請求欄位條件之間沒有固定的全域優先順序,仍會依規則段落中的排列順序比對。較廣泛的位址條件若排在前面,可能先於後面的網域例外命中;範圍過大的請求識別條件,也可能改變原本依網域區分的結果。維護時應一併檢查條件類型與排列順序,並為需要保留的例外設計測試目標,不能只按類別檢查個別規則語法。

如果同一網域在不同測試中使用不同策略,請確認是否分別連線至 IPv4 與 IPv6 位址、是否命中不同網段,以及解析結果是否改變。不要立刻刪除其中一種位址類型來修正問題。先確認目標實際使用的位址,再檢查現有規則對兩種位址類型是否表達相同意圖;若確實受環境限制,請記錄條件與還原方式,並在網路環境變更後重新驗證。

06 · 比對順序、例外與 FINAL

閱讀 [Rule] 的關鍵,是從上往下尋找第一個符合條件的規則,並採用該規則指定的策略。規則比對不是投票,也不會彙整所有符合項目後再選擇結果。精確規則不會自動優先於後綴規則,網域規則也不會自動優先於位址規則。優先順序首先取決於行序;了解這一點,才能說明為何兩份使用相同規則的檔案,僅因排列不同就產生不同結果。

將具體例外排在廣泛條件之前

常見的安排方式是將明確例外放在前面,一般分類排在中間,最終規則置於最後。例如某個 API 需要代理,而同網域的其他主機需要直連,就應將 API 的精確條件排在父網域後綴規則之前。「例外在前」是整理原則,不是要求一律套用固定的分類順序。若業務上需要讓某個位址範圍優先,也應先確認這項決定會涵蓋哪些網域請求,再據此安排順序,而不是先照抄排列方式再解釋用途。

[Rule]
DOMAIN,api.example.com,PROXY
DOMAIN-SUFFIX,example.com,DIRECT
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

以 API 主機為例,第一行符合條件後就會選擇代理,後面的父網域條件不會再改變結果。以同網域的其他主機為例,第一行不符合,接著由後綴條件決定直連。若目標不屬於上述網域,也不在列出的位址範圍內,就會繼續往下比對。逐條推演時,請標明每個條件是「符合」、「不符合」或「目前資訊不足,無法判定」,不要憑印象直接跳到最終結論。

FINAL 是最終規則,不是自動修復

FINAL 在前面的條件都未命中時,提供最終策略。它不需要網域參數,寫法例如 FINAL,PROXY 或 FINAL,DIRECT。通常將它放在規則段落末尾,讓前面的具體條件有機會比對。若將最終規則放在前面,後續規則在一般逐條比對流程中就失去作用。也不應利用多條最終規則來表示備用關係;保留一項明確的最終選擇,較容易確認設定意圖。

範圍較廣的關鍵字、位址歸屬和父網域後綴,都可能讓後面的例外規則無法命中。若某條規則看似一直沒有作用,請往上檢查所有可能涵蓋它的條件,不要只尋找相同文字。完全相同的重複行容易發現,彼此範圍重疊的規則則較不明顯。可以先列出問題目標,從目前檔案第一行開始逐條推演,找出第一個符合的位置,再決定要移動哪一條規則;不要將目標規則隨意複製到多個段落。

使用對照表驗證修改意圖

調整規則順序前,請為每種類型的目標選一個明確範例:精確例外主機、父網域中的其他主機、區域網路位址,以及未命中前述條件的目標。先記下各範例預期採用的策略,修改後再查看實際紀錄。若只測試發生問題的主機,可能修正了例外,卻破壞父網域中的其他請求。測試範例不必很多,但應涵蓋規則邊界;每增加一項廣泛條件,至少再測試一個可能被錯誤涵蓋的目標。

測試目標預期首先命中的規則預期策略
api.example.com精確網域例外PROXY
www.example.com父網域後綴條件DIRECT
192.168.1.20私有位址網段DIRECT
未命中前置條件的目標FINALPROXY

合併不同來源的設定時,尤其要檢查各原始檔案的最終策略和例外規則。兩份檔案分開使用時都正常,合併後不一定仍能正常運作,因為它們可能採用相反的預設策略。先選定一致的最終策略,再將必要例外加入同一組規則,最後檢查彼此是否覆蓋。不要保留兩套完整的規則順序,並期待用戶端能自行理解兩位作者不同的設定意圖。

測試結束後,移除臨時置頂的規則。排查時暫時將目標規則移到最前面,有助於確認連線路徑;但若長期保留,可能遮蔽之後新增的服務例外。最終規則應放回容易理解的位置,並記錄變更原因。若要進一步排查規則命中正確但仍無法連線的情況,可閱讀最後一章的驗證流程,或參閱規則與故障排除 FAQ;不要繼續調整順序來處理與順序無關的問題。

07 · Host 與 URL Rewrite 的適用範圍

[Host] 和 [URL Rewrite] 都可能改變最終的存取結果,但兩者並非相同操作。前者建立網域與 IP 位址的固定對應;後者則改寫符合條件的網址。兩者也不同於 [Rule] 中的策略選擇。排查時應分別確認:請求要連線至哪個名稱、該名稱對應哪個位址、網址是否改變,以及連線使用哪種策略。若將這些問題混為一談,就容易混淆解析、轉址與分流。

Host 固定對應適用於位址已知且可維護的情況

以下範例將文件中的示例主機對應到文件用途的位址,用來說明格式,不應當作真實服務位址使用。等號左側是網域,右側是 IP 位址,並非代理策略。設定固定對應後,相關解析可以使用指定位址,但連線是否經由代理,仍由實際規則和目前模式決定。因此,同一網域同時設定固定對應和代理規則並不衝突,兩者描述的是不同層次的行為。

[Host]
lab.example.com = 192.0.2.10

固定對應適用於管理責任明確的測試服務或內部服務,不宜任意用在依賴動態調度的公共網站。目標服務遷移、位址變更或內容傳遞方式調整後,舊位址可能失效,甚至指向不再適用的服務。設定檔仍可儲存,不代表位址仍然正確。維護時應記錄對應用途與驗證條件;目標恢復正常解析後,及時確認是否仍需保留這項覆蓋,避免臨時措施變成長期問題。

存取加密網站時,固定 IP 位址不會自動改寫憑證中的網域,也無法消除憑證驗證失敗。若目標位址未提供對應主機的服務,可能出現連線成功但頁面錯誤、憑證不符或服務拒絕等情況。此時不應忽略安全提示來「證明對應有效」,而應核對位址歸屬與服務設定。使用網域連線與直接輸入 IP 位址並非完全相同的測試;後者可能改變目標收到的主機資訊。

URL Rewrite 處理可比對的網址

改寫規則通常包含比對式、替換目標和動作。以下範例會將示例主機的 HTTP 網址重新導向至同一主機的 HTTPS 網址,並保留後續路徑。比對式中的句點以反斜線跳脫,代表網域中的實際句點,而非任意字元;開頭錨點則限制從網址起始位置比對。這段內容只用來說明語法與適用範圍,不代表所有目標都應採用這種轉址方式。

[URL Rewrite]
^http://example\.com/(.*)$ https://example.com/$1 302

這裡的 302 是重新導向動作,$1 則引用前面括號所捕捉的內容。修改比對式時,應一併確認比對範圍和替換結果,特別留意斜線是否重複、路徑是否遺失,以及查詢參數是否依預期保留。先以不含個人資訊的簡單測試路徑驗證,再確認實際服務流程需要保留的參數。不要將含有驗證資訊的完整請求貼到公開問題描述中。

加密請求與循環轉址需分開檢查

一般加密連線不會自動讓用戶端看見完整網址路徑,因此即使設定檔中有改寫段落,也不代表所有加密請求都會被檢查或改寫。本頁不要求為了規則分流而額外啟用解密處理;多數依網域選擇策略的需求,也不必透過網址改寫完成。若只是希望某個網站走代理,應直接考慮網域規則,而不是嘗試為該網站的所有網址新增轉址。

循環轉址常見原因是目標網址再次符合原本的比對式,或兩條規則互相將網址改回去。測試時觀察最後網址是否反覆變動,並逐一停用最近新增的改寫規則進行比較。目標服務本身也可能執行轉址,因此不能將所有循環都歸因於本機規則。先保留最精簡的改寫條件,再比較停用該段落後的結果,才能確認循環發生在本機處理階段,還是目標服務回應階段。

合併含有改寫規則的設定前,應逐條確認規則用途、目標網域和適用範圍,不要只檢查檔案能否儲存。範圍過廣的比對式可能影響無關路徑;固定對應也可能讓多個功能連線到錯誤位址。若用途不明,請保留原始檔案,暫時不要啟用相應段落。修正分流問題時,優先使用分流規則;需要固定解析或改寫網址時,再分別加入,並為每項變更安排獨立測試與還原方式。

08 · 驗證、排錯與設定檔維護

設定檔是否正確,最終應比對「預期的處理方式」和「實際觀察結果」,不能只看檔案是否能儲存。成功儲存主要表示文字通過目前的解析檢查;請求命中預期規則,表示分流判斷符合設定目的;實際服務操作成功,才表示目前的網路、伺服器、目標服務與服務條件在本次測試中都符合需求。這三種結論涵蓋範圍不同,記錄時應分開說明,不要把局部成功寫成一切正常。

建立可還原的最精簡驗證流程

開始前先保留目前使用的設定檔副本,記錄目前選取的項目、全域路由模式、網路環境和現有伺服器選擇。接著每次只修改一類條件,例如只調整目標網域規則的位置,不要同時更換解析來源。儲存並確認已生效後,重新發起目標請求,查看 App 目前提供的連線或請求紀錄,核對主機、目標位址、命中規則和處理策略。不同平台的紀錄入口可能不同,請以實際介面為準。

若實際策略與預期不同,先確認模式和設定檔是否正確,再依規則順序由上往下檢查涵蓋關係。若策略正確但連線失敗,改查伺服器參數、目標服務和目前網路。若只有部分頁面功能失敗,應找出失敗請求對應的主機,而不是重寫整份規則。依照這些分支排查可減少無關變更,也能簡化還原操作:撤回本次修改後,應能回到測試前已知的狀態。

觀察到的現象優先檢查項目不宜直接推論
檔案無法儲存段落名稱、逗號、欄位數量與換行伺服器已經失效
請求策略與預期不同目前使用的設定檔、模式與第一個命中條件目標網站一定故障
策略正確但連線失敗伺服器參數、解析結果與目標可達性再加一條相同規則就能恢復
首頁正常但登入失敗驗證 API、轉址與相關網域父網域規則已涵蓋所有服務

不要在規則中修復伺服器與訂閱問題

現有伺服器顯示逾時時,應逐項檢查位址、連接埠、驗證資訊、協定相關欄位和系統時間,並確認與自己的資訊相符。不要將所有連線失敗都改為直連,也不要認為不斷更新訂閱就會改變本機規則順序。訂閱更新主要影響訂閱提供的資料;設定檔可能來自其他來源,兩者是否連動應以目前的使用方式為準。詳細排查順序請參閱節點逾時與連線失敗逐項排查。

管理多個現有訂閱時,先區分訂閱群組、手動新增項目與設定檔,刪除前確認要刪除的是哪一類內容。更新後出現重複項目,不代表需要複製更多規則;也不要為了辨識項目,就把含有連線憑證的完整網址寫進設定備註。可參閱多個訂閱的分組與重複項目管理,先整理來源,再確認連線與規則的關係。

遠端更新與本機修改分開保存

遠端設定檔更新可能會取代本機修改,實際情況取決於檔案來源和更新方式。若要長期保留自訂規則,先確認目前的檔案是獨立的本機副本,還是仍由遠端內容管理。更新前保留副本,更新後比較基本欄位、例外規則和最終策略,不要只看檔案名稱是否相同。避免同時維護多個用途不明的同名檔案;名稱可以說明用途,但不能取代生效狀態檢查。

分享排查資訊時,只提供必要的規則片段和已去除敏感資訊的現象描述。伺服器位址、訂閱連結、密碼、驗證欄位和私人存取目標都可能涉及隱私,分享前應先移除。範例請統一替換為文件網域,同時保留規則類型和排列順序,如此仍可討論涵蓋關係。截圖也應檢查通知、清單與紀錄中的敏感內容,不要因為只截取部分畫面,就假設其中不含憑證。

跨裝置使用時,應分別確認系統網路環境及目前用戶端可用的設定入口,不要把某台裝置的結果直接套用到所有平台。Shadowrocket 提供 iPhone、iPad、Mac、Windows、Android 和 Linux 版本;iPhone / iPad 於 App Store 一次性付費 $2.99,Mac(Apple 晶片與 Intel)、Windows、Android、Linux 版本免費。取得用戶端與首次安裝方式請參閱下載頁安裝說明;iPhone / iPad 的系統需求請以 App Store 頁面標示為準。

結束排查時,切回日常使用的路由模式,移除臨時測試規則,保留最終檔案與簡短的變更紀錄,再執行先前規劃的邊界測試範例。日後若再遇到問題,先比較網路、伺服器和設定檔有哪些變動,不必急著推翻所有設定。首次匯入與連線步驟請返回快速入門教學;不清楚欄位含義時可查閱術語表,常見操作問題則可參考常見問題。讓操作流程、欄位查閱與故障排除各自負責明確的任務。