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 不对 检查规则是否启用、内容是否合法、随机池是否有可用项,以及是否存在更高优先级的标签页或域名规则,然后刷新页面。
数据很多时导入报存储错误 文件和浏览器同步存储均有大小限制;精简规则或列表后重试,并核对现有配置。
远程文件修改后插件没有变化 远程加载是手动的一次性导入;再次输入地址并加载、确认。