UA Pro 設定教學

設定匯入、匯出與遠端設定

備份、移轉及手動編寫設定,以及從遠端網址載入設定。

適用版本:UA Pro 1.5.0

本文適用於 UA Pro 1.5.0,介紹如何備份、移轉、手動編寫設定,以及從遠端網址載入設定。新版使用完整快照格式,設定檔的 version 為 2。

匯入前,請先在目標瀏覽器匯出一份備份。 每次匯入都會以檔案中的完整快照取代全域規則、整組網域規則、兩個 UA 資料庫及資源網域備援開關,不會逐條合併。"globalRule": null 表示清除目標瀏覽器的全域規則。

01匯出設定

  1. 點擊瀏覽器工具列中的 UA Pro 圖示。
  2. 開啟「更多操作」→「匯入/匯出設定」。
  3. 點擊「匯出設定」,儲存下載的 .json 檔案。
  4. 檔案名稱類似 ua-switcher-config-2026-11-16.json。檔名中的日期依 UTC 產生,可能與本地日期相差一天。

檔案包含以下持續保存的設定:

  • 全域規則及其啟用或暫停狀態。
  • 整組網域規則及其啟用或暫停狀態。
  • 自訂 UA 分類和項目。
  • 附加文字分類和項目。
  • 「資源網域備援」開關。

檔案不包含分頁規則、已抽取的隨機 UA 綁定、目前開啟的分頁、介面語言、主題和浮動面板設定。匯入後這些項目不會從備份還原;目標瀏覽器已有的分頁規則也不會被匯入操作清除,因此可能繼續覆蓋網域或全域規則。

匯出檔案是可讀的 JSON 明文。若自訂 UA 或分類包含不想公開的資訊,請妥善保管備份。

02從本機檔案匯入

  1. 在目標瀏覽器中開啟 UA Pro →「更多操作」→「匯入/匯出設定」。
  2. 先點擊「匯出設定」,保留目標瀏覽器原有設定,以便需要時還原。
  3. 點擊「匯入設定」,選擇 .json 檔案。
  4. 閱讀覆寫提示及規則、清單數量;點擊「查看設定內容」可在確認前檢查完整 JSON。選擇「取消」不會寫入。確認後等待「設定已匯入!」提示。若確認期間設定發生變化,擴充功能會要求重新操作。
  5. 檢查全域和網域規則、自訂清單及資源網域備援開關;檢查是否有既存的分頁規則覆蓋它們。重新整理要測試的網頁,再確認 UA。

擴充功能會先檢查檔案,再嘗試安裝規則,最後寫入持續保存的設定。若安裝或寫入失敗,會嘗試還原為瀏覽器目前儲存的規則;若提示無法還原,請檢查實際設定。瀏覽器同步或其他視窗同時修改設定時,不應將此程序視為跨裝置交易。

03從遠端網址載入

遠端設定使用與本機備份相同的 JSON 內容。這是一次性的手動載入及匯入,不是自動更新的訂閱。

  1. 先匯出設定備份,或依照下文準備 JSON 檔案。
  2. 將檔案放在目標瀏覽器可存取的 HTTPS 服務上,取得直接回傳 JSON 內容的完整網址,例如 https://example.com/ua-pro/config.json。此處網址僅為範例,請替換為自己的實際網址。
  3. 在 UA Pro →「更多操作」→「匯入/匯出設定」中展開「遠端設定」,貼上網址後點擊「載入」。
  4. 載入和格式檢查通過後,擴充功能會顯示確認視窗及遠端主機名稱;點擊「查看設定內容」可檢查實際下載的完整 JSON。確認後會依照與本機匯入相同的規則更新設定;取消則不會匯入。
  5. 伺服器上的檔案變更後,若要使用新內容,須再次輸入網址、載入並確認。重新開啟面板時,網址不會自動保留。

只接受 HTTPS 直接連結,不接受 HTTP、網址中的使用者名稱或密碼、網址片段,也不會跟隨重新導向。請求不攜帶瀏覽器 Cookie 或登入憑證、不傳送 Referer,並略過快取;因此需要登入 Cookie 的服務不適用。UA Pro 不會將本擴充功能設定的 UA 規則套用於此請求,但其他擴充功能或網路設備仍可能改寫請求。網址可以包含查詢參數,含存取權杖的網址應像密碼一樣保管。請使用可信任的網址,並確認回應直接是 JSON 檔案,而非登入頁面或顯示程式碼的 HTML 頁面。

本機檔案與遠端回應均限制為 128 KiB;遠端讀取限時 10 秒,並計算實際讀取內容的大小。瀏覽器同步儲存另有較小的單項配額,即使檔案未超過 128 KiB,仍可能因規則或單一資料庫過大而無法儲存。發生錯誤時,請檢查伺服器是否回傳狀態碼 200 和有效 JSON、憑證是否有效、網址是否發生重新導向,以及網路是否可連線。

04完整 JSON 範例

以下範例可儲存為 UTF-8 編碼的 config.json。範例網域和 UA 值僅供說明;替換前請先備份現有設定。JSON 區分大小寫,字串使用英文雙引號,最後一個元素後不要加逗號,也不要在 JSON 內撰寫註解。

JSON
{
  "version": 2,
  "type": "ua-switcher-config",
  "timestamp": "2026-11-16T06:00:00.000Z",
  "data": {
    "globalRule": {
      "enabled": true,
      "mode": "builtin",
      "params": {
        "os": "Windows",
        "uaKey": "Edge 125 (Latest)"
      }
    },
    "domainRules": {
      "example.com": {
        "enabled": true,
        "mode": "custom",
        "params": {
          "category": "手机示例",
          "value": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1"
        }
      },
      "app.example.com": {
        "enabled": true,
        "mode": "append",
        "params": {
          "category": "测试标记",
          "value": "MyApp/1.0"
        }
      },
      "random.example.com": {
        "enabled": true,
        "mode": "random",
        "params": {
          "pool": "custom:随机示例",
          "strategy": "page"
        }
      },
      "paused.example.com": {
        "enabled": false,
        "mode": "custom",
        "params": {
          "category": "测试",
          "value": "ExampleAgent/1.0"
        }
      }
    },
    "userCustomData": {
      "手机示例": [
        "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1"
      ],
      "随机示例": [
        "ExampleAgent/1.0",
        "ExampleAgent/2.0"
      ],
      "测试": [
        "ExampleAgent/1.0"
      ]
    },
    "userAppendData": {
      "测试标记": [
        "MyApp/1.0"
      ]
    },
    "resourceDomainFallback": false
  }
}

此範例設定一個內建全域 UA 和四條網域規則。app.example.com 等更具體的子網域規則優先於 example.com;暫停的規則不參與生效比對,父網域或全域規則仍可能接替生效。實際網站能否識別範例 UA,取決於網站本身。

05頂層欄位與覆寫行為

欄位 範例 作用
version 2 必填。新版只接受數值 2。
type "ua-switcher-config" 必填。設定類型識別碼,必須完全符合此字串。
timestamp "2026-11-16T06:00:00.000Z" 必填。使用帶有毫秒和 Z 的 UTC 時間;僅供記錄,不決定規則生效時間。
data { ... } 必填。存放完整設定的物件,包含下表全部欄位。
data 中的欄位 正確格式 本版本匯入時的行為
globalRule 一個規則物件,或 null 規則物件取代現有全域規則;null 清除現有全域規則。
domainRules { "域名": 规则对象 } 整個物件取代原有網域規則;{} 會清空它們。
userCustomData { "分类": ["UA", ...] } 整個物件取代原有自訂 UA 資料庫;{} 會清空它。
userAppendData { "分类": ["追加文本", ...] } 整個物件取代原有附加文字資料庫;{} 會清空它。
resourceDomainFallback true 或 false JSON 布林值:開啟或關閉資源網域備援。

五個欄位全部必填,除 globalRule 外不能使用 null。缺少欄位、未知欄位和重複的 JSON 鍵會遭拒絕;舊版本或部分設定也不會匯入。網域規則和兩個資料庫按整組取代:例如只提供一個網域的 domainRules,會取代目標瀏覽器中其他既有網域規則。建議基於新版實際匯出的檔案編輯,並完整保留需要的項目。

資源網域備援只在主頁面沒有有效的分頁、網域或全域 UA 時,才可能依資源請求的目標網域套用規則;這不表示所有跨網域資源都會覆蓋主頁面規則。

06如何編寫規則物件

全域規則和每條網域規則使用相同結構:

JSON
{
  "enabled": true,
  "mode": "custom",
  "params": {
    "category": "常用",
    "value": "ExampleAgent/1.0"
  }
}

enabled: true 表示啟用,false 表示暫停。mode 決定 params 的欄位:

6.1 內建 UA:builtin

JSON
{
  "enabled": true,
  "mode": "builtin",
  "params": { "os": "Windows", "uaKey": "Edge 125 (Latest)" }
}

os 和 uaKey 必須與該擴充功能版本內部預設的鍵完全一致,不一定等於介面上翻譯後的顯示文字。最穩妥的方法是在介面中選好預設、匯出設定,再複製對應的 params。預設清單隨版本變更時應重新核對。

6.2 自訂 UA:custom

JSON
{
  "enabled": true,
  "mode": "custom",
  "params": { "category": "常用", "value": "ExampleAgent/1.0" }
}

value 是完整的 UA 字串。category 用於分類和介面編輯;建議在 userCustomData 的同名分類中也包含此值。規則生效時讀取的是規則自己的 value,手動匯入規則不會自動將此值加入自訂資料庫。

6.3 附加文字:append

JSON
{
  "enabled": true,
  "mode": "append",
  "params": { "category": "应用标记", "value": "MyApp/1.0" }
}

擴充功能會在目前瀏覽器原始 UA 後加一個空格,再附加 value。建議在 userAppendData 的同名分類中也保留此文字;匯入規則不會自動填入清單。

6.4 隨機 UA:random

JSON
{
  "enabled": true,
  "mode": "random",
  "params": { "pool": "custom:随机示例", "strategy": "page" }
}

strategy 必須為 "page"(每次完整頁面載入時抽取)或 "tab"(依規則和分頁保持)。隨機抽取允許重複,連續兩次相同不一定表示沒有重新抽取。

常見 pool 值:

值 隨機來源
all 所有內建 UA、自訂 UA 和附加文字產生的 UA
builtin 所有內建 UA
builtin_desktop、builtin_mobile、builtin_legacy 內建桌面、行動或舊裝置分類
builtin_gaming、builtin_smarttv、builtin_communication、builtin_social 對應的內建分類
custom 所有自訂分類中的 UA
custom:分类名 userCustomData 中指定分類的 UA
append_all 所有附加文字對應的 UA
append:分类名 userAppendData 中指定分類的附加文字所對應的 UA

冒號後的分類名稱必須與資料庫中的鍵一致。已啟用的隨機規則必須有可用候選項,否則檔案會遭拒絕。

07手動編輯時的檢查

  • domainRules 的鍵填寫網域,例如 example.com、shop.example.com,不要填寫 https://、路徑、連接埠或空格。網域規則也會比對下層子網域;*.example.com 在目前版本同樣包含 example.com 本身,並非「僅子網域」。
  • 分類名稱可以使用中文,必須是非空字串,不能包含控制字元或危險的雙向文字控制符;__proto__、prototype、constructor 不能作為分類名稱。UA 和附加文字建議使用可列印的 ASCII 字元,不要包含換行、定位字元或其他控制字元;單條 UA 最多 4096 個字元。文字中的英文雙引號和反斜線需依 JSON 規則跳脫。
  • 每個分類對應字串陣列,例如 "常用": ["Agent/1.0", "Agent/2.0"]。即使只有一項也要保留方括號。空分類可寫成 []。
  • true、false 和 null 不能加雙引號;"false" 是字串,不是布林值。
  • 檔案須為有效的 UTF-8 和 JSON,不允許重複鍵。擴充功能還會檢查結構、欄位類型、規則、預設名稱和隨機池;語法正確不代表規則一定可用。

設定檔可以改變瀏覽器傳送給網站的 UA。HTTPS 用來保護傳輸,並不保證伺服器提供的設定符合你的意願;請只匯入來源可信任的檔案,確認前查看內容,並在重新整理目標網頁後核對實際效果。

08常見問題

現象 排查方法
提示檔案格式不正確 檢查 UTF-8、JSON 語法、重複鍵、版本、必填欄位和規則類型;使用新版匯出檔案作為範本。
遠端載入失敗 檢查 HTTPS 憑證、直接連結、網路和回傳內容;不允許重新導向、Cookie 登入或 HTTP。
匯入後規則變少 網域規則和兩個資料庫按整組取代;從匯入前的備份還原,或在新檔案中補齊需要保留的項目。
匯入空的全域規則後,網頁仍使用其他 UA 檢查現有分頁規則或相符的網域規則;它們可能優先於全域規則。
顯示成功但 UA 不正確 檢查規則是否啟用、內容是否合法、隨機池是否有可用項目,以及是否存在優先順序較高的分頁或網域規則,然後重新整理頁面。
資料很多時匯入出現儲存錯誤 檔案和瀏覽器同步儲存都有大小限制;精簡規則或清單後重試,並核對現有設定。
遠端檔案修改後擴充功能沒有變化 遠端載入是手動的一次性匯入;請再次輸入網址並載入、確認。