Hướng dẫn cấu hình UA Pro

Nhập, xuất cấu hình và cấu hình từ xa

Sao lưu, di chuyển, tự viết cấu hình và tải cấu hình từ địa chỉ từ xa.

Phiên bản áp dụng: UA Pro 1.5.0

Bài viết áp dụng cho UA Pro 1.5.0, hướng dẫn sao lưu, di chuyển, tự viết cấu hình và tải cấu hình từ địa chỉ từ xa. Phiên bản mới dùng định dạng ảnh chụp đầy đủ; version của tệp cấu hình là 2.

Trước khi nhập, hãy xuất một bản sao lưu trên trình duyệt đích. Mỗi lần nhập, ảnh chụp đầy đủ trong tệp sẽ thay thế quy tắc toàn cục, toàn bộ quy tắc tên miền, hai thư viện UA và công tắc dùng dự phòng tên miền tài nguyên; các mục không được hợp nhất riêng lẻ. "globalRule": null có nghĩa là xóa quy tắc toàn cục của trình duyệt đích.

01Xuất cấu hình

  1. Nhấp biểu tượng UA Pro trên thanh công cụ trình duyệt.
  2. Mở “Thêm” → “Nhập hoặc xuất cấu hình”.
  3. Nhấp “Xuất cấu hình” và lưu tệp .json đã tải xuống.
  4. Tên tệp có dạng như ua-switcher-config-2026-11-16.json. Ngày trong tên tệp được tạo theo UTC và có thể lệch một ngày so với ngày địa phương.

Tệp chứa các cấu hình được lưu lâu dài sau:

  • Quy tắc toàn cục và trạng thái bật hoặc tạm dừng của quy tắc.
  • Toàn bộ quy tắc tên miền và trạng thái bật hoặc tạm dừng của từng quy tắc.
  • Danh mục và mục UA tùy chỉnh.
  • Danh mục và mục văn bản nối thêm.
  • Công tắc “Dùng dự phòng tên miền tài nguyên”.

Tệp không chứa quy tắc thẻ, các liên kết UA ngẫu nhiên đã được chọn, thẻ đang mở, ngôn ngữ giao diện, chủ đề và cài đặt lớp phủ nổi. Các mục này không được khôi phục từ bản sao lưu sau khi nhập; các quy tắc thẻ đã có trên trình duyệt đích cũng không bị thao tác nhập xóa, nên có thể tiếp tục ưu tiên hơn quy tắc tên miền hoặc toàn cục.

Tệp xuất là JSON dạng văn bản thuần có thể đọc được. Nếu UA tùy chỉnh hoặc danh mục chứa thông tin không muốn công khai, hãy bảo quản bản sao lưu cẩn thận.

02Nhập từ tệp cục bộ

  1. Trên trình duyệt đích, mở UA Pro → “Thêm” → “Nhập hoặc xuất cấu hình”.
  2. Trước tiên nhấp “Xuất cấu hình” để giữ cấu hình ban đầu của trình duyệt đích và có thể khôi phục khi cần.
  3. Nhấp “Nhập cấu hình”, rồi chọn tệp .json.
  4. Đọc cảnh báo ghi đè và số lượng quy tắc, danh sách; nhấp “Xem nội dung cấu hình” để kiểm tra toàn bộ JSON trước khi xác nhận. Chọn “Hủy bỏ” sẽ không ghi dữ liệu. Sau khi xác nhận, đợi thông báo “Đã nhập cấu hình!”. Nếu cài đặt thay đổi trong lúc xác nhận, tiện ích sẽ yêu cầu thực hiện lại.
  5. Kiểm tra quy tắc toàn cục và tên miền, danh sách tùy chỉnh và công tắc dùng dự phòng tên miền tài nguyên; kiểm tra xem quy tắc thẻ hiện có có ưu tiên hơn chúng không. Làm mới trang cần kiểm tra rồi xác nhận UA.

Tiện ích kiểm tra tệp trước, sau đó thử cài đặt quy tắc và cuối cùng ghi cấu hình lưu lâu dài. Nếu cài đặt hoặc ghi thất bại, tiện ích sẽ thử khôi phục các quy tắc hiện được lưu trong trình duyệt; nếu thông báo không thể khôi phục, hãy kiểm tra cài đặt thực tế. Khi đồng bộ trình duyệt hoặc cửa sổ khác đồng thời thay đổi cấu hình, không nên coi quy trình này là một giao dịch xuyên thiết bị.

03Tải từ địa chỉ từ xa

Cấu hình từ xa sử dụng cùng nội dung JSON như bản sao lưu cục bộ. Đây là thao tác tải và nhập thủ công một lần, không phải đăng ký tự động cập nhật.

  1. Trước tiên xuất bản sao lưu cấu hình hoặc chuẩn bị tệp JSON theo hướng dẫn bên dưới.
  2. Đặt tệp trên dịch vụ HTTPS mà trình duyệt đích truy cập được, rồi lấy địa chỉ đầy đủ trả trực tiếp nội dung JSON, ví dụ https://example.com/ua-pro/config.json. Địa chỉ này chỉ là ví dụ; hãy thay bằng địa chỉ thực tế của bạn.
  3. Trong UA Pro, mở “Thêm” → “Nhập hoặc xuất cấu hình”, mở rộng “Cấu hình từ xa”, dán địa chỉ rồi nhấp vào “Tải”.
  4. Sau khi tải và kiểm tra định dạng thành công, tiện ích hiển thị hộp xác nhận và tên máy chủ từ xa; nhấp “Xem nội dung cấu hình” để kiểm tra toàn bộ JSON thực sự đã tải xuống. Xác nhận sẽ cập nhật cài đặt theo cùng quy tắc như nhập cục bộ; hủy sẽ không nhập.
  5. Sau khi tệp trên máy chủ thay đổi, nếu muốn dùng nội dung mới, bạn cần nhập lại địa chỉ, tải và xác nhận. Địa chỉ không tự động được giữ lại khi mở lại bảng.

Chỉ chấp nhận liên kết trực tiếp HTTPS; không chấp nhận HTTP, tên người dùng hoặc mật khẩu trong địa chỉ, mảnh URL và không theo chuyển hướng. Yêu cầu không mang Cookie trình duyệt hoặc thông tin đăng nhập, không gửi Referer và bỏ qua bộ nhớ đệm; do đó dịch vụ cần Cookie đăng nhập không phù hợp. UA Pro không áp dụng các quy tắc UA được cấu hình trong tiện ích này cho yêu cầu đó, nhưng tiện ích khác hoặc thiết bị mạng vẫn có thể sửa yêu cầu. Địa chỉ có thể chứa tham số truy vấn; hãy bảo quản địa chỉ chứa mã truy cập như mật khẩu. Hãy dùng địa chỉ đáng tin cậy và đảm bảo phản hồi trực tiếp là tệp JSON, không phải trang đăng nhập hay trang HTML hiển thị mã.

Tệp cục bộ và phản hồi từ xa đều bị giới hạn 128 KiB; thời gian đọc từ xa tối đa 10 giây và kích thước được tính theo nội dung thực sự đọc. Bộ nhớ đồng bộ của trình duyệt còn có hạn mức nhỏ hơn cho từng mục, nên tệp chưa vượt 128 KiB vẫn có thể không lưu được nếu quy tắc hoặc một thư viện quá lớn. Nếu gặp lỗi, hãy kiểm tra máy chủ có trả trạng thái 200 và JSON hợp lệ không, chứng chỉ có hợp lệ không, địa chỉ có chuyển hướng không và mạng có thể kết nối không.

04Ví dụ JSON đầy đủ

Có thể lưu ví dụ sau thành config.json mã hóa UTF-8. Tên miền và giá trị UA trong ví dụ chỉ để minh họa; hãy sao lưu cấu hình hiện có trước khi thay thế. JSON phân biệt chữ hoa và chữ thường; dùng dấu ngoặc kép ASCII cho chuỗi, không đặt dấu phẩy sau phần tử cuối và không viết chú thích trong 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
  }
}

Ví dụ này đặt một UA toàn cục có sẵn và bốn quy tắc tên miền. Quy tắc tên miền con cụ thể hơn như app.example.com được ưu tiên hơn example.com; quy tắc tạm dừng không tham gia đối sánh có hiệu lực, và quy tắc tên miền cha hoặc toàn cục vẫn có thể được áp dụng thay thế. Trang web thực tế có nhận diện được UA ví dụ hay không tùy thuộc vào chính trang web đó.

05Trường cấp cao nhất và cách ghi đè

Trường Ví dụ Tác dụng
version 2 Bắt buộc. Phiên bản mới chỉ chấp nhận số 2.
type "ua-switcher-config" Bắt buộc. Mã nhận dạng loại cấu hình, phải khớp chính xác với chuỗi này.
timestamp "2026-11-16T06:00:00.000Z" Bắt buộc. Dùng thời gian UTC có mili giây và Z; chỉ để ghi nhận, không quyết định thời điểm quy tắc có hiệu lực.
data { ... } Bắt buộc. Đối tượng chứa cấu hình đầy đủ, gồm tất cả các trường trong bảng dưới đây.
Các trường trong data Định dạng đúng Cách xử lý khi nhập ở phiên bản này
globalRule Một đối tượng quy tắc hoặc null Đối tượng quy tắc thay thế quy tắc toàn cục hiện có; null xóa quy tắc toàn cục hiện có.
domainRules { "域名": 规则对象 } Toàn bộ đối tượng thay thế các quy tắc tên miền cũ; {} xóa hết chúng.
userCustomData { "分类": ["UA", ...] } Toàn bộ đối tượng thay thế thư viện UA tùy chỉnh cũ; {} xóa hết thư viện đó.
userAppendData { "分类": ["追加文本", ...] } Toàn bộ đối tượng thay thế thư viện văn bản nối thêm cũ; {} xóa hết thư viện đó.
resourceDomainFallback true hoặc false Giá trị Boolean JSON: bật hoặc tắt chức năng dùng dự phòng tên miền tài nguyên.

Cả năm trường đều bắt buộc; ngoài globalRule không trường nào được dùng null. Trường thiếu, trường không xác định và khóa JSON trùng lặp sẽ bị từ chối; cấu hình phiên bản cũ hoặc không đầy đủ cũng không được nhập. Quy tắc tên miền và hai thư viện được thay thế theo từng nhóm hoàn chỉnh: chẳng hạn domainRules chỉ chứa một tên miền sẽ thay thế cả các quy tắc tên miền khác đã có trên trình duyệt đích. Nên chỉnh sửa dựa trên tệp thực sự được xuất từ phiên bản mới và giữ đầy đủ các mục cần dùng.

Chức năng dùng dự phòng tên miền tài nguyên chỉ có thể áp dụng quy tắc theo tên miền đích của yêu cầu tài nguyên khi trang chính không có UA thẻ, tên miền hoặc toàn cục có hiệu lực; điều này không có nghĩa mọi tài nguyên khác miền đều ghi đè quy tắc trang chính.

06Cách viết đối tượng quy tắc

Quy tắc toàn cục và từng quy tắc tên miền dùng cùng một cấu trúc:

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

enabled: true nghĩa là bật, false nghĩa là tạm dừng. mode quyết định các trường của params:

6.1 UA có sẵn: builtin

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

os và uaKey phải khớp chính xác với khóa được đặt sẵn bên trong phiên bản tiện ích đó; chúng không nhất thiết giống chữ hiển thị đã dịch trên giao diện. Cách chắc chắn nhất là chọn giá trị đặt sẵn trên giao diện, xuất cấu hình rồi sao chép params tương ứng. Hãy kiểm tra lại khi danh sách giá trị đặt sẵn thay đổi theo phiên bản.

6.2 UA tùy chỉnh: custom

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

value là chuỗi UA đầy đủ. category dùng để phân loại và chỉnh sửa trên giao diện; nên đưa giá trị này vào danh mục cùng tên trong userCustomData. Khi áp dụng quy tắc, tiện ích đọc value của chính quy tắc; nhập quy tắc thủ công không tự động thêm giá trị vào thư viện tùy chỉnh.

6.3 Văn bản nối thêm: append

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

Tiện ích thêm một dấu cách sau UA gốc của trình duyệt hiện tại, rồi nối thêm value. Nên giữ văn bản này trong danh mục cùng tên của userAppendData; nhập quy tắc không tự động điền danh sách.

6.4 UA ngẫu nhiên: random

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

strategy phải là "page" (chọn mỗi lần tải toàn bộ trang) hoặc "tab" (giữ theo quy tắc và thẻ). Việc chọn ngẫu nhiên cho phép trùng lặp, nên hai lần liên tiếp giống nhau không nhất thiết nghĩa là không chọn lại.

Các giá trị pool thường gặp:

Giá trị Nguồn ngẫu nhiên
all Tất cả UA có sẵn, UA tùy chỉnh và UA tạo từ văn bản nối thêm
builtin Tất cả UA có sẵn
builtin_desktop, builtin_mobile, builtin_legacy Danh mục máy tính, di động hoặc thiết bị cũ có sẵn
builtin_gaming, builtin_smarttv, builtin_communication, builtin_social Các danh mục có sẵn tương ứng
custom UA trong tất cả danh mục tùy chỉnh
custom:分类名 UA trong danh mục được chỉ định ở userCustomData
append_all UA tương ứng với tất cả văn bản nối thêm
append:分类名 UA tương ứng với văn bản nối thêm trong danh mục được chỉ định ở userAppendData

Tên danh mục sau dấu hai chấm phải khớp với khóa trong thư viện. Quy tắc ngẫu nhiên được bật phải có ứng viên khả dụng, nếu không tệp sẽ bị từ chối.

07Kiểm tra khi chỉnh sửa thủ công

  • Khóa của domainRules phải là tên miền, ví dụ example.com, shop.example.com; không ghi https://, đường dẫn, cổng hoặc dấu cách. Quy tắc tên miền cũng khớp với các tên miền con cấp dưới; trong phiên bản hiện tại, *.example.com cũng bao gồm chính example.com, không phải “chỉ tên miền con”.
  • Tên danh mục có thể dùng tiếng Trung, phải là chuỗi không rỗng và không được chứa ký tự điều khiển hoặc ký tự điều khiển văn bản hai chiều nguy hiểm; __proto__, prototype, constructor không được dùng làm tên danh mục. Nên dùng ký tự ASCII có thể in cho UA và văn bản nối thêm; không được chứa xuống dòng, tab hoặc ký tự điều khiển khác; mỗi UA tối đa 4096 ký tự. Dấu ngoặc kép ASCII và dấu gạch chéo ngược trong văn bản phải được thoát theo quy tắc JSON.
  • Mỗi danh mục tương ứng với một mảng chuỗi, ví dụ "常用": ["Agent/1.0", "Agent/2.0"]. Giữ dấu ngoặc vuông ngay cả khi chỉ có một mục. Danh mục rỗng có thể viết là [].
  • Không đặt true, false và null trong dấu ngoặc kép; "false" là chuỗi, không phải giá trị Boolean.
  • Tệp phải là UTF-8 và JSON hợp lệ, không cho phép khóa trùng lặp. Tiện ích còn kiểm tra cấu trúc, kiểu trường, quy tắc, tên giá trị đặt sẵn và tập ngẫu nhiên; cú pháp đúng không đảm bảo quy tắc có thể sử dụng.

Tệp cấu hình có thể thay đổi UA mà trình duyệt gửi tới trang web. HTTPS bảo vệ quá trình truyền nhưng không đảm bảo cấu hình do máy chủ cung cấp đúng với ý muốn của bạn; chỉ nhập tệp từ nguồn đáng tin cậy, xem nội dung trước khi xác nhận và kiểm tra kết quả thực tế sau khi làm mới trang đích.

08Câu hỏi thường gặp

Hiện tượng Cách kiểm tra
Thông báo định dạng tệp không đúng Kiểm tra UTF-8, cú pháp JSON, khóa trùng lặp, phiên bản, trường bắt buộc và loại quy tắc; dùng tệp xuất từ phiên bản mới làm mẫu.
Không tải được từ xa Kiểm tra chứng chỉ HTTPS, liên kết trực tiếp, mạng và nội dung trả về; không cho phép chuyển hướng, đăng nhập bằng Cookie hoặc HTTP.
Số quy tắc giảm sau khi nhập Quy tắc tên miền và hai thư viện được thay thế theo từng nhóm hoàn chỉnh; khôi phục từ bản sao lưu đã tạo trước khi nhập hoặc bổ sung các mục cần giữ vào tệp mới.
Đã nhập quy tắc toàn cục rỗng nhưng trang vẫn dùng UA khác Kiểm tra quy tắc thẻ hiện có hoặc quy tắc tên miền khớp; chúng có thể được ưu tiên hơn quy tắc toàn cục.
Báo thành công nhưng UA không đúng Kiểm tra quy tắc có được bật không, nội dung có hợp lệ không, tập ngẫu nhiên có mục khả dụng không và có quy tắc thẻ hoặc tên miền ưu tiên cao hơn không, rồi làm mới trang.
Lỗi lưu trữ khi nhập nhiều dữ liệu Tệp và bộ nhớ đồng bộ của trình duyệt đều có giới hạn kích thước; giảm bớt quy tắc hoặc danh sách, thử lại và kiểm tra cấu hình hiện có.
Tiện ích không thay đổi sau khi sửa tệp từ xa Tải từ xa là thao tác nhập thủ công một lần; nhập lại địa chỉ, tải và xác nhận.