代理助手

适用于 Chrome、Firefox 和 Edge 的浏览器代理管理扩展

简体中文 | 繁體中文 | English | 日本語 | Français | Deutsch | Español | Português | Русский | 한국어

代理助手用于在浏览器内管理 HTTP、HTTPS、SOCKS4 和 SOCKS5 代理。扩展提供禁用、手动和自动三种运行模式，并将代理节点、使用场景、路由规则、规则订阅、配置同步和诊断工具集中在同一个设置页面中。

Chrome、Firefox 和 Edge 均使用 Manifest V3。Edge 使用与 Chrome 相同的 Chromium 构建包。项目采用原生 JavaScript、jQuery 和浏览器扩展 API 开发，不依赖前端构建框架。

主要功能

代理节点与运行模式

• 管理 HTTP、HTTPS、SOCKS4 和 SOCKS5 代理节点。
• 支持代理地址、端口、用户名、密码、颜色和启用状态等配置。
• 在扩展弹窗中切换禁用、手动和自动模式。
• 手动模式使用选定节点，可配置不使用代理的地址。
• 自动模式根据节点的使用代理地址生成 PAC 脚本，并支持直连或拒绝连接两种回退策略。
• 支持单个测试和批量测试代理节点，并显示测试耗时或失败状态。

当前界面对 SOCKS5 节点禁用认证字段；Chrome 的代理 API 不支持 SOCKS5 用户名和密码认证。

代理场景

• 将不同网络环境的代理节点分别保存在多个场景中。
• 在设置页面或扩展弹窗中切换当前场景。
• 支持场景新增、重命名、删除、排序和节点迁移。
• 可为场景指定默认代理，并按星期和时间段配置自动启用规则。

规则订阅

• 集中维护可被多个代理节点复用的规则订阅。
• 支持 AutoProxy、Switchy Legacy、Switchy Omega 和 PAC 格式。
• 可查看订阅原文、解析结果、使用代理规则和直连规则。
• 支持规则反转以及手动、1 分钟、6 小时、12 小时、1 天和 5 天更新周期。
• 订阅更新由扩展后台任务执行。

配置、同步与诊断

• 使用 JSON 文件导入和导出配置，可选择是否包含订阅配置及订阅缓存。
• 使用浏览器原生同步存储在同一浏览器账号的设备间推送或拉取配置。
• 使用 GitHub Gist 推送或拉取配置，并支持定时同步。
• 原生同步数据按 7 KB 分块写入，并在设置页面显示当前配额占用情况。
• 检查当前代理控制状态、PAC 脚本状态以及可能的扩展冲突。
• 提供分级运行日志，可在设置页面筛选、刷新、复制或清空。

界面设置

• 支持浅色、深色和按时间自动切换主题。
• 支持使用 JSON 编辑自定义主题颜色。
• 支持简体中文、繁体中文、英语、日语、法语、德语、西班牙语、葡萄牙语、俄语和韩语。

安装

从发布包安装

普通用户可以直接从浏览器扩展商店安装：

• Chrome 网上应用店：适用于 Chrome，也可在允许安装 Chrome 扩展的 Edge 中使用。
• Firefox Add-ons：适用于 Firefox。

也可以前往 GitHub Releases 下载对应版本：

• Chrome、Edge 等 Chromium 浏览器使用 ProxyAssistant_<版本>_chrome.zip。
• Firefox 构建包含 ProxyAssistant_<版本>_firefox.zip 和 ProxyAssistant_<版本>_firefox.xpi。

在 Chrome 或 Edge 中安装 ZIP 包时，需要先解压文件，然后在扩展管理页面开启开发者模式并选择“加载已解压的扩展程序”。仓库发布流程生成的 Firefox XPI 是构建产物，能否直接安装取决于当前 Firefox 的扩展签名策略；普通用户建议使用 Firefox Add-ons 商店版本。

从源码加载

仓库为 Chrome 和 Firefox 分别维护了清单文件。建议先使用构建脚本生成对应浏览器的完整目录或安装包，避免直接修改 src/manifest.json：

src/manifest.json 与 src/manifest_chrome.json 保持一致，供 Chrome / Edge 直接加载 src/ 调试。修改 Chrome 清单时需同步两份文件；后台脚本使用 importScripts() 加载依赖，须保持默认的经典脚本类型。

npm ci
make build VERSION=dev

构建完成后，解压 build/ProxyAssistant_dev_chrome.zip，再通过 Chrome 或 Edge 的扩展管理页面加载解压后的目录。调试 Firefox 时，可以解压 Firefox ZIP，在 about:debugging 的“此 Firefox”页面选择“临时载入附加组件”，并打开目录中的 manifest.json。生成 XPI 需要本机已安装 web-ext；如果未安装，构建脚本仍会生成 Firefox 的 ZIP 和 TAR.GZ 文件，但会跳过 XPI。

基本使用

1. 安装后点击浏览器工具栏中的代理助手图标。
2. 点击设置按钮进入完整设置页面。
3. 在“代理节点”中新增代理，填写协议、地址和端口；需要时再填写认证和路由规则。
4. 返回弹窗，选择禁用、手动或自动模式。
5. 手动模式下选择一个节点；自动模式下由 PAC 脚本按节点规则决定连接方式。

常见配置方式：

• 始终使用一个代理：选择手动模式并选中目标节点。
• 指定网站使用代理：为节点填写“使用代理的地址”，然后选择自动模式。
• 指定网站保持直连：为手动模式节点填写“不使用代理的地址”，或通过订阅提供直连规则。
• 区分办公、家庭等环境：分别创建场景，并在弹窗中快速切换。

数据与权限

扩展申请以下权限：

权限	用途
proxy	读取和修改浏览器代理配置
storage	保存本地配置，并支持浏览器原生同步
webRequest、webRequestAuthProvider	响应代理认证请求
alarms	执行订阅更新、场景自动切换和定时同步
<all_urls>	生成适用于网页请求的代理规则并读取当前站点信息

配置默认保存在 chrome.storage.local。代理用户名和密码是代理配置的一部分，也会进入导出的配置文件以及主动推送的同步数据；GitHub Token 和 Gist ID 不会写入导出或同步内容。请妥善保管导出文件，并在启用浏览器同步或 Gist 同步前确认其符合你的数据安全要求。

拉取远端配置会覆盖本地业务配置，但保留本地同步连接信息和同步计划。执行拉取前，建议先导出一份本地配置作为备份。

隐私政策：Proxy Assistant Privacy Policy

开发

环境要求

• Node.js 20（与 GitHub Actions 使用的版本一致）
• npm
• Chrome、Firefox 或 Edge，用于浏览器内验证
• web-ext，仅在构建 Firefox XPI 时需要

安装依赖：

npm ci

测试

npm test                    # 运行全部 Jest 测试
npm run test:unit           # 单元测试
npm run test:integration    # 集成测试
npm run test:e2e            # 端到端测试
npm run test:watch          # 监听模式
npm run test:coverage       # 覆盖率测试

也可以使用 Makefile 中的入口：

make test
make test_unit
make test_integration
make test_e2e
make test_nocache

构建

make build VERSION=dev

构建脚本会清理 build/，为两个浏览器选择各自的 Manifest，并生成以下文件：

build/
├── ProxyAssistant_dev_chrome.zip
├── ProxyAssistant_dev_chrome.tar.gz
├── ProxyAssistant_dev_firefox.zip
├── ProxyAssistant_dev_firefox.tar.gz
└── ProxyAssistant_dev_firefox.xpi

如果系统中没有 web-ext，最后一个文件不会生成。

在 GitHub 网页打包测试分支

1. 打开仓库的 Actions → Build Test Packages → Run workflow。
2. 在 Use workflow from 中选择包含此工作流的分支。可选的 ref 输入框用于指定要打包的分支、标签或提交 SHA；留空时打包所选工作流分支的代码。
3. 点击 Run workflow，完成后在运行详情的 Artifacts 或构建摘要中下载测试包。

工作流复用 make build，生成上述 5 种 Release 同类型产物，保留 14 天。下载的 Artifact 是外层 ZIP，解压后可取得各浏览器的安装包。文件名使用 test-<运行编号>-<重跑次数>-<提交短 SHA> 标识，扩展 Manifest 版本保持目标代码中的版本。此流程仅手动运行，不创建标签或 GitHub Release。

首次使用前，需要将工作流合入默认分支，GitHub 才会显示手动运行入口，详见 GitHub 手动运行工作流文档。目标代码需包含 Makefile、script/build.sh 和 src/。Chrome / Edge 解压 Chrome ZIP 后加载；Firefox 可解压 Firefox ZIP，通过 about:debugging 临时加载 manifest.json，生成的 XPI 未签名。

项目结构

ProxyAssistant/
├── src/
│   ├── _locales/             # 浏览器国际化资源
│   ├── css/                  # 设置页面和弹窗样式
│   ├── images/               # 扩展图标
│   ├── js/                   # 页面、代理、存储、同步和后台逻辑
│   ├── main.html             # 设置页面
│   ├── popup.html            # 扩展弹窗
│   ├── manifest_chrome.json  # Chrome Manifest V3
│   └── manifest_firefox.json # Firefox Manifest V3
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── script/build.sh           # Chrome 和 Firefox 打包脚本
├── readme/                   # 其他语言 README
├── release/                  # 各版本发布说明
├── Makefile
└── package.json

核心模块包括：

文件	职责
src/js/worker.js	应用代理设置、生成 PAC、处理认证、定时任务与后台消息
src/js/main.js	设置页面初始化和跨模块协调
src/js/popup.js	弹窗中的模式、场景和节点切换
src/js/proxy.js	代理节点表单、列表和测试交互
src/js/scenarios.js	场景管理及时间规则
src/js/subscription.js	订阅管理、解析和刷新计划
src/js/config.js	配置格式、迁移、导入与导出
src/js/storage.js	本地配置缓存与持久化
src/js/sync.js	浏览器原生同步和 GitHub Gist 同步
src/js/detection.js	代理控制状态和 PAC 诊断

项目的代码约定和测试要求见 AGENTS.md。

浏览器说明

• Chrome 使用 Manifest V3 Service Worker。
• Firefox 使用 Manifest V3 background script，最低支持版本由当前清单设为 Firefox 142。
• Edge 使用 Chrome 构建包，可通过 Chrome 网上应用店安装，也可在开发者模式下加载解压后的 Chrome 构建目录。项目当前的专用清单和自动化构建目标仍为 Chrome 与 Firefox。
• 同时启用多个代理或 VPN 扩展可能造成浏览器代理控制权冲突，可在“代理状态”页面查看诊断结果。

反馈与贡献

问题和功能建议请提交到 GitHub Issues。提交改动前，请至少运行与改动相关的测试；涉及浏览器代理行为时，建议在 Chrome、Firefox 和 Edge 中进行验证。

许可证

本项目使用 MIT License。

正则规则匹配约定

自动代理规则支持 /表达式/flags。不包含路径分隔符的正则匹配主机名（默认不区分大小写）；包含 / 或 \/ 的正则匹配完整 URL（默认区分大小写）。可以用 host:/表达式/flags 或 url:/表达式/flags 明确指定匹配目标。Chrome 与 Firefox 使用相同规则；HTTPS 的 URL 路径是否可见仍由浏览器的 PAC API 决定。

多条规则可用换行或逗号分隔，正则表达式内部的逗号（如 {1,3}）会被保留。无效或不满足安全限制的正则不会参与匹配。

PAC 订阅通过处理规则中的左右边界提取文本列表，不执行远程 JavaScript，也不等同于解释任意 PAC 脚本。提取结果最多保留 20,000 条；解析失败时保留之前的缓存。

原生同步传输元数据 v5 为每次上传分配独立分块前缀，兼容读取 v4；它独立于配置文件版本 v5。为保留失败时的上一份备份，上传期间需要容纳新旧两份数据。旧版固定键分块不自动清理，以免与仍使用旧版本的设备冲突。