本文适用于 UA Pro 1.5.0,介绍如何备份、迁移、手动编写配置,以及从远程地址加载配置。新版使用完整快照格式,配置文件的 version 为 2。
导入前先在目标浏览器导出一份备份。 每次导入都会用文件中的完整快照替换全局规则、整组域名规则、两个 UA 库及资源域名回退开关,不会逐条合并。"globalRule": null 表示清除目标浏览器的全局规则。
01导出配置
- 点击浏览器工具栏中的 UA Pro 图标。
- 打开“更多操作” → “导入/导出配置”。
- 点击“导出配置”,保存下载的
.json文件。 - 文件名类似
ua-switcher-config-2026-11-16.json。文件名中的日期按 UTC 生成,可能与本地日期相差一天。
文件包含以下持久配置:
- 全局规则及其启用或暂停状态。
- 整组域名规则及其启用或暂停状态。
- 自定义 UA 分类和条目。
- 追加文本分类和条目。
- “资源域名回退”开关。
文件不包含标签页规则、已经抽取的随机 UA 绑定、当前打开的标签页、界面语言、主题和悬浮层设置。导入后这些项目不会从备份恢复;目标浏览器已有的标签页规则也不会被导入操作清除,因此可能继续覆盖域名或全局规则。
导出文件是可读的 JSON 明文。如果自定义 UA 或分类包含不想公开的信息,请妥善保管备份。
02从本地文件导入
- 在目标浏览器中打开 UA Pro →“更多操作”→“导入/导出配置”。
- 先点击“导出配置”,保留目标浏览器的原配置,以便需要时恢复。
- 点击“导入配置”,选择
.json文件。 - 阅读覆盖提示和规则、列表数量;点击“查看配置内容”可在确认前检查完整 JSON。选择“取消”不会写入。确认后等待“配置已导入”提示。如果确认期间设置发生变化,插件会要求重新操作。
- 检查全局和域名规则、自定义列表及资源域名回退开关;检查是否有现存的标签页规则覆盖它们。刷新需要测试的网页,再确认 UA。
插件会先检查文件,再尝试安装规则,最后写入持久配置。如果安装或写入失败,会尝试恢复为浏览器中当前保存的规则;若提示无法恢复,请检查实际设置。浏览器同步或其他窗口同时修改配置时,不应把该过程理解为跨设备事务。
03从远程地址加载
远程配置使用与本地备份相同的 JSON 内容。它是一次性的手动加载和导入,不是自动更新的订阅。
- 先导出配置备份,或者按照下文准备 JSON 文件。
- 将文件放到目标浏览器能访问的 HTTPS 服务上,获得直接返回 JSON 内容的完整地址,例如
https://example.com/ua-pro/config.json。这里的地址只是示例,请替换成自己的实际地址。 - 在 UA Pro →“更多操作”→“导入/导出配置”的“远程配置”中粘贴地址,点击“加载远程配置”。
- 加载和格式检查通过后,插件会显示确认框及远程主机名;点击“查看配置内容”可检查实际下载的完整 JSON。确认会按本地导入相同的规则更新设置;取消不会导入。
- 文件在服务器上改变后,如需使用新内容,需再次输入地址、加载并确认。重新打开面板时,地址不会自动保留。
只接受 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 内写注释。
{
"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规则对象怎么写
全局规则和每条域名规则使用相同结构:
{
"enabled": true,
"mode": "custom",
"params": {
"category": "常用",
"value": "ExampleAgent/1.0"
}
}
enabled: true 表示启用,false 表示暂停。mode 决定 params 的字段:
6.1 内置 UA:builtin
{
"enabled": true,
"mode": "builtin",
"params": { "os": "Windows", "uaKey": "Edge 125 (Latest)" }
}
os 和 uaKey 必须与该插件版本内部预设的键完全一致,它们不一定等于界面上翻译后的显示文字。最稳妥的方法是在界面中选好预设、导出配置,再复制对应的 params。预设列表随版本变化时应重新核对。
6.2 自定义 UA:custom
{
"enabled": true,
"mode": "custom",
"params": { "category": "常用", "value": "ExampleAgent/1.0" }
}
value 是完整的 UA 字符串。category 用于分类和界面编辑;建议在 userCustomData 的同名分类中同时包含该值。规则生效读取的是规则自己的 value,手动导入规则不会自动把该值加入自定义库。
6.3 追加文本:append
{
"enabled": true,
"mode": "append",
"params": { "category": "应用标记", "value": "MyApp/1.0" }
}
插件会在当前浏览器原始 UA 后加一个空格,再追加 value。建议在 userAppendData 的同名分类中同时保留该文本;导入规则不会自动填充列表。
6.4 随机 UA:random
{
"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 不对 | 检查规则是否启用、内容是否合法、随机池是否有可用项,以及是否存在更高优先级的标签页或域名规则,然后刷新页面。 |
| 数据很多时导入报存储错误 | 文件和浏览器同步存储均有大小限制;精简规则或列表后重试,并核对现有配置。 |
| 远程文件修改后插件没有变化 | 远程加载是手动的一次性导入;再次输入地址并加载、确认。 |