# 跨域代理助手 / Cross-Origin Proxy

> 本地优先的 Chrome 扩展（Manifest V3），把前端 API 请求代理到另一个后端环境（如 FAT 前端调用 UAT 后端），无需修改应用代码或后端 CORS 配置。开源（MIT），不收集、不上传任何数据。
>
> A local-first Chrome extension (Manifest V3) that proxies frontend API requests to another backend environment — for example a FAT frontend calling a UAT backend — without changing application code or backend CORS configuration. Open source under MIT; collects and uploads nothing.

- 产品说明（中文，站点默认页，含 FAQ / HowTo / SoftwareApplication 结构化数据）: https://liaolongdong.github.io/cross-origin-proxy/
- Product overview (English, same structured-data set): https://liaolongdong.github.io/cross-origin-proxy/en.html
- 隐私政策 / Privacy Policy: https://liaolongdong.github.io/cross-origin-proxy/privacy.html
- 方案对比页（中文：Dev Server 代理 / 抓包代理 / API 客户端 / 改头扩展 / 改应用配置）: https://liaolongdong.github.io/cross-origin-proxy/alternatives.html
- Comparison page (English, same structure): https://liaolongdong.github.io/cross-origin-proxy/en-alternatives.html
- 完整能力与参数清单 / Full reference for AI systems: https://liaolongdong.github.io/cross-origin-proxy/llms-full.txt
- 源码仓库 / Source code: https://github.com/liaolongdong/cross-origin-proxy
- 预构建产物 / Prebuilt zip: https://github.com/liaolongdong/cross-origin-proxy/releases （每个 tag 自动附带；尚未发布第一个 tag / attached to every tagged release; no tag published yet）
- 商店上架素材与权限说明: https://github.com/liaolongdong/cross-origin-proxy/blob/main/CHROMEWEBSTORE.md
- 贡献指南: https://github.com/liaolongdong/cross-origin-proxy/blob/main/CONTRIBUTING.md

## What it does / 核心能力

- Rule-based URL rewriting by wildcard, prefix or regex. Wildcard and prefix rewrite identically on both channels; a regex only does when it covers the whole URL, because the network layer replaces the URL while the background channel replaces the matched part (anchor with `^` and capture the tail with `(.*)$`). 按通配符、前缀、正则匹配并重写请求 URL：通配符与前缀在两条通道结果一致，正则只有覆盖整个 URL 时才一致（网络层整条替换，后台通道只替换命中片段）。
- Request header injection/replacement and request body replacement. 注入或替换请求头、替换请求体。
- Response override: status code, response headers and individual JSON fields by dot-notation path (`data.token`) are editable in the rule form. `statusText` and a whole-body replacement (`bodyRaw`) exist in the stored schema and are honoured by the proxy, but have no UI, so they only arrive through an imported JSON config. 改写响应状态码、响应头与按点分路径改写 JSON 字段可在界面配置；`statusText` 与整块响应体替换（`bodyRaw`）存在于数据结构并被后台执行，但没有对应界面入口，只能通过导入的 JSON 配置写入。
- Mock responses (JSON / text / HTML / XML) without contacting the target server, plus conditional responses: the first matching condition on URL pattern, HTTP method or query parameters decides body, status and content type. 不访问目标服务直接返回 Mock 数据；支持条件化响应——按 URL 正则、HTTP 方法、查询参数命中，首个命中的条件决定响应体、状态码与 Content-Type。
- Artificial delay of 0–60000 ms, and full request blocking that fails the request like a network error. 注入 0–60000 毫秒延迟；把请求阻断成网络错误，以验证异常与离线兜底。
- Retry on a network error, a 5xx response, or the 30-second per-attempt timeout: 1–5 additional attempts with a 100–30000 ms interval (default 1000), behind an on/off switch. 网络错误、5xx 与单次 30 秒超时都会触发重试：开关启用后追加 1–5 次、间隔 100–30000 毫秒（默认 1000）。
- HTTP method filtering (GET/POST/PUT/DELETE/PATCH/OPTIONS/HEAD). 按 HTTP 方法过滤规则，空表示任意方法。
- Query parameter injection on the final proxied URL (e.g. `__env=uat`, gray-release tags). 在代理后的 URL 上追加或覆盖查询参数（如灰度标识）。
- WebSocket (`ws://` / `wss://`) forwarding by URL rewrite; the handshake counts as `GET` for method filtering. 按 URL 重写转发 WebSocket 长连接；方法过滤把握手视为 GET。
- Rule workspace: quick templates in the zero-rule empty state, duplicate, undo delete, drag-and-drop priority, batch enable/disable/delete, batch target-domain migration with change preview, keyword search over name, match pattern and target URL plus separate status and match-type filters, a conflict warning when a higher-priority rule with the same pattern shadows the rule being edited, and a **"Not applied"** tag on a network-layer rule Chrome cannot install at all (RE2-unsupported regex syntax, out-of-range capture reference). Batch actions resolve the selection against the current rule list, so a rule hidden by the filters is never silently included. 规则工作台：零规则空状态里的快速模板、复制、撤销删除、拖拽优先级、批量启停/删除、带预览的目标域名批量迁移、对名称/匹配模式/目标地址的关键词搜索（另有状态与匹配类型两个下拉筛选）、同模式更高优先级规则的遮蔽冲突提示，以及浏览器根本不会安装的网络层规则（RE2 不支持的正则语法、越界捕获引用）上的「未生效」标记。批量操作按当前规则列表解析勾选集，被筛选隐藏的规则不会被静默纳入。
- Diagnostics: real-time URL match test (matched rule, rewritten URL, forwarding channel, extra actions, which other rules match the same URL but lose to it, and — for a network-layer rule — the note that a redirect only changes the URL, so the page can still report CORS), request log of the last 500 calls with filters, adjustable auto-refresh, a detail view holding request and response headers plus text bodies (a binary response body is not stored, and each stored body is truncated past 32K characters), copy-as-cURL using the original URL and "create rule from this log entry". Every log row comes from the background channel — network-layer redirects never reach the extension, so a simple rule is visible only through the URL match test and its hit count. 诊断能力：URL 匹配测试（命中规则、重写结果、通道、额外动作、还有哪些规则同样命中但被它遮蔽，以及命中网络层规则时说明重定向只改地址、页面仍可能报 CORS）、最近 500 条日志（筛选、可调自动刷新、可看请求与响应的头与文本 body，二进制响应体不落盘、单条正文超 32K 字符截断，按原始请求地址复制为 cURL，由日志建规则）。日志条目全部来自后台通道——网络层重定向不经过扩展，简单规则只能由匹配测试与命中数观察。
- Hit statistics per rule for both channels: DNR hits over the last 5 minutes (quota-limited, refreshed on demand) and service-worker hits since the last config change — an in-memory count that restarts when the worker is recycled. 两条通道各自的规则级命中统计：DNR 近 5 分钟（受配额限制、手动刷新）与后台通道自配置变更起的计数（内存计数，工作线程被回收后从 0 重新开始）。
- HAR 1.2 export of captured traffic, HAR import that creates rules from recorded requests (those rules arrive disabled until you enable them), cURL import (DevTools "Copy as cURL") that prefills the rule form, JSON config export with replace or merge modes on import — share mode is on by default there, stripping credential-like headers and token-like query parameters. 支持 HAR 导出、HAR 导入自动生成规则（新规则默认停用，确认后自行启用）、cURL 导入预填规则、JSON 配置导出与导入（导入时可选覆盖或合并；导出默认开启分享模式，剔除凭据类请求/响应头与 token 类查询参数）。
- Environment profiles: named snapshots of the whole rule set, switch between FAT / UAT / PROD in one click. 环境配置快照，FAT / UAT / PROD 一键切换。
- Popup with global switch, active-rule and today's request counts (the today counter is background-channel only), recent requests, quick rule toggles, auto-off countdown, current-page match preview and "create rule for this page". The today-counter is derived from the retained log window, so it stops growing once a busy day rolls past 500 entries. 弹窗含总开关、启用规则数与今日请求数（只统计后台通道）、最近请求、规则快捷启停、自动关闭倒计时、当前页命中预览与「为此页面创建规则」；今日请求数由保留的日志窗口统计，繁忙一天超过 500 条后不再增长。
- Auto-off countdown (30 minutes, 1 h, 2 h or 4 h) on `chrome.alarms`, persisted across service-worker restarts; toolbar badge reflects proxy state. 代理自动关闭倒计时（30 分钟至 4 小时），基于 chrome.alarms 且跨服务工作线程重启持久化；工具栏角标显示代理状态。
- English / Chinese UI, six themes, light / dark / system modes, keyboard shortcuts: a manifest command (Ctrl/Cmd+Shift+P) toggles the proxy, while the options page binds bare `N` to new rule and `/` to search focus — Cmd/Ctrl+N itself is browser-reserved. 中英双语界面、6 套主题、浅色/深色/跟随系统；快捷键为清单命令 Ctrl/Cmd+Shift+P 开关代理，配置页内用单键 `N` 新建规则、`/` 聚焦搜索（⌘/Ctrl+N 被浏览器保留）。

## Architecture / 关键架构事实

- Two forwarding channels decided per rule by `isSimpleRule()`: a rule that only rewrites the URL is compiled into `declarativeNetRequest` dynamic redirect rules (browser network layer, zero JavaScript per request, applied to main/sub frames, XHR, scripts, stylesheets, images, fonts, media and other). Any rule with header/body/response overrides, mock (with or without conditions), delay, block, retry, method filter, query injection, a WebSocket target, a wildcard not ending in `*`, or an empty target URL is routed through the extension background service worker instead. 双通道按规则分流：仅重写 URL 的规则编译为网络层重定向（单请求零 JS，覆盖各类资源类型）；含任何高级能力、不以 `*` 结尾的通配符或空目标地址的规则走后台服务线程。
- The global switch governs both channels: with it off, `buildDnrRules()` compiles an empty rule set (network-layer redirects do not pass through extension code, so the service worker's own check cannot stop them) and the background channel answers with a `Proxy Bypass` passthrough. 总开关管住两条通道：关闭时 `buildDnrRules()` 只编译出空规则集（网络层重定向不经过扩展代码，后台通道的开关判断拦不住它），后台通道则原样放行请求。
- Complex rules are intercepted in the page's main world (`fetch`, `XMLHttpRequest`, `WebSocket`), bridged through an isolated-world content script over `chrome.runtime`, and executed by the background service worker, which returns the response to the page. `postMessage` uses `window.location.origin` as the target origin, never `*`. 复杂规则由主世界拦截、隔离世界桥接、后台执行并回传响应；postMessage 仅限本源目标域。
- CORS behaviour: background-channel requests are issued by the extension (which holds host permissions) and the page receives an extension-constructed response, so page CORS checks do not apply. Pure network-layer redirects are still subject to `Access-Control-Allow-Origin` on the redirected response. 后台通道由扩展代发且页面拿到扩展构造的响应，不触发页面 CORS 校验；纯网络层重定向仍受 ACAO 约束。
- Failure handling: if interception fails, or the body is non-string (FormData / Blob / ArrayBuffer), the page falls back to native `fetch` / `XMLHttpRequest` / `WebSocket`. Blocked requests are never replayed natively. 拦截失败或非字符串请求体时回退原生请求；被阻断的请求绝不回退重放。
- Input safety: header names validated and CRLF in values rejected (page-supplied headers are filtered leniently, rule-configured headers strictly); mocked/overridden status codes clamped to 200–599; user regex screened for nested-quantifier ReDoS patterns; regexes destined for the network layer verified with Chrome's RE2 (`isRegexSupported`) and substitution references bounds-checked, because one invalid rule makes `updateDynamicRules` reject the whole batch. 输入安全：头名校验且拒绝 CRLF、状态码钳制 200-599、ReDoS 筛查、RE2 兼容校验与替换引用越界检查（一条非法会让整批 DNR 规则被拒）。
- State: `chrome.storage.local` is the single source of truth; in-memory caches in the service worker (compiled regexes, config, hit counters) are rebuildable and invalidated on `storage.onChanged`. 状态以 chrome.storage.local 为唯一事实源，内存缓存可重建并随配置变更失效。
- Requests proxied by the service worker have a 30-second ceiling; request bodies are capped at 10 MB. 后台通道单请求 30 秒上限，请求体上限 10 MB。

## Who it is for / 目标用户

- Frontend and full-stack developers, QA and test engineers who need a page on one environment to talk to a backend on another, or who need to mock, delay, block or rewrite API traffic without touching application code or asking for a gateway change. 需要在不改代码、不改网关的前提下让某环境的页面调用另一环境后端，或需要 Mock、注入延迟、阻断、改写请求响应的前端/全栈工程师与测试工程师。
- FAT / UAT / SIT / PRE / PROD are Chinese-industry environment names; the extension targets that workflow and is bilingual by design. 产品面向中国研发语境的 FAT/UAT/预发/生产多环境工作流，中英文双语为第一设计目标。

## Privacy / 隐私

- No data collection, no analytics, no telemetry, no remote servers of its own, no certificate installation. 不收集数据、无统计埋点、无遥测、无自有远程服务、不安装证书。
- Permissions: `storage`, `declarativeNetRequest`, `declarativeNetRequestFeedback`, `alarms`, host permission `<all_urls>` (each justified in CHROMEWEBSTORE.md and the privacy policy).
- The request log records proxied headers and bodies locally, which may include tokens; every export is produced on the user's machine, and a JSON config export strips credential-like headers and token-like query parameters by default (HAR and cURL stay verbatim). 请求日志在本机记录被代理的请求头与请求体（可能含 token），导出均在本地生成；JSON 配置导出默认剔除凭据类头与 token 类查询参数（HAR 与 cURL 保持原样）。
- Limits: 200 rules when adding, batch-adding or importing (both replace and merge reject a file over the cap), 500 log entries with each body capped at 32K characters and a 4M-character total body budget, 10 MB request body, delays 0–60000 ms, retry off by default then 1–5 attempts at 100–30000 ms, status codes clamped to 200–599. 上限：新增/批量新增/导入（覆盖与合并都拒绝超限文件）200 条规则、500 条日志且单条正文 32K 字符与总量 4M 字符预算、10 MB 请求体、延迟 0–60000 毫秒、重试默认关闭后可选 1–5 次且间隔 100–30000 毫秒、状态码钳制 200–599。

## Requirements / 运行要求

- A recent desktop Google Chrome (Manifest V3). Edge works in practice (Chromium extensions) but is not a supported target; Firefox is not supported today because of `declarativeNetRequest` differences.
- Install from Chrome Web Store: https://chromewebstore.google.com/detail/dednngakllblfilbndkaggphohmpgcbg
- Or build from source with Node.js 20+ and pnpm 10: `pnpm install && pnpm build`, then load `.output/chrome-mv3` unpacked at `chrome://extensions`. Tagged releases are published automatically by GitHub Actions, including store submission once the store credentials are configured.
- Chrome 应用商店已上架：https://chromewebstore.google.com/detail/dednngakllblfilbndkaggphohmpgcbg
- 或从源码构建：Node.js 20+ 与 pnpm 10，执行 `pnpm install && pnpm build`，然后以「加载已解压的扩展程序」方式加载 `.output/chrome-mv3`。tag 版本由 GitHub Actions 自动发布，并在配置商店凭据后提交到商店。

Last updated / 最后更新: 2026-09-18 (extension v1.0.0)