front-proxy

front-proxy

通过真实域名（如 local-dev.mylivedomain.com），经由 HTTP 或 HTTPS 访问本地端口上的应用（如 localhost:3000）。

运行时，front-proxy 会将你的域名添加到 /etc/hosts，并将其指向 127.0.0.1，同时在 80 和 443 端口运行反向代理。停止后，它会将这些域名移除。代理会读取每个请求的 Host 标头，并将请求转发到映射给该域名的端口。HTTPS 使用来自 mkcert 的本地可信证书。由于映射由操作系统管理，因此它适用于你机器上的所有浏览器和工具，而不只是某一个。

  Browser, curl, Playwright...
          │
          │  https://local-dev.mylivedomain.com
          ▼
  ┌───────────────────────────────────────────────┐
  │ /etc/hosts                                    │
  │   127.0.0.1  local-dev.mylivedomain.com       │
  └───────────────────────────────────────────────┘
          │
          │  127.0.0.1:443  (or :80 for http)
          ▼
  ┌───────────────────────────────────────────────┐
  │ front-proxy                                   │
  │   1. TLS with the domain's mkcert certificate │
  │   2. Host header → port, from proxyHosts.json │
  │        local-dev.mylivedomain.com → 3000      │
  │      (unknown host → 502)                     │
  └───────────────────────────────────────────────┘
          │
          │  http://127.0.0.1:3000
          ▼
  Your local app

为什么使用

有些第三方服务只接受来自允许列表中域名的请求（例如 Stripe 和 Google Tag Manager），有些 API 则会通过 CORS 阻止 localhost。浏览器扩展可以在一个浏览器中伪造域名。front-proxy 适用于整个操作系统，因此也能覆盖其他浏览器、命令行工具和无头 Playwright 运行，无需额外配置。

要求

• Node.js 22.12 或更高版本
• macOS 或 Linux（它会修改 /etc/hosts 并使用 sudo）
• mkcert，仅用于 HTTPS（在 macOS 上运行 brew install mkcert）

安装

npm install -g front-proxy

现在可以在终端中使用 front-proxy 命令了。

如果 npm install -g 因 EACCES 错误而失败，说明你的 npm 全局目录归 root 所有。在 Linux 上使用系统 Node，或使用官方 macOS 安装程序时，这种情况很常见。请使用通过 nvm 或 Homebrew 安装的 Node，或运行 sudo npm install -g front-proxy。

更新：

npm update -g front-proxy

你的域名和证书保存在 ~/.front-proxy 中（参见配置），因此更新和重新安装时都会保留它们。

如需从克隆的仓库运行，请参阅开发。

使用方法

front-proxy add local-dev.livedomain.com:3000   # map a domain to a local port
front-proxy                                     # start the proxy

然后打开 http://local-dev.livedomain.com（设置好证书后，也可以使用 https://）。

命令	说明	需要 sudo
front-proxy	在端口 80 和 443 上启动代理，并将域名添加到 /etc/hosts，直到代理停止	是
front-proxy --persist-hosts	同上，但代理停止后仍保留 /etc/hosts 中的域名（简写为 -p）	是
front-proxy --no-admin	启动时不启用管理页面	是
front-proxy add <host:port>	将域名添加到代理配置	否
front-proxy remove <host>	从代理配置中移除域名	否
front-proxy list	列出已配置的域名	否
front-proxy generate-certs [host]	使用 mkcert 为一个或全部域名创建 HTTPS 证书	否
front-proxy mcp	在 stdio 上为代码助手运行 MCP 服务	否
front-proxy --help	显示帮助	否

只有启动代理时才会通过 sudo 请求密码，因为它需要绑定端口 80/443 并编辑 /etc/hosts。密码不会被保存。

域名会写入 /etc/hosts 中的单个区块：

# <FRONT-PROXY-HOSTS>
# > local-dev.livedomain.com < Host added by front-proxy
127.0.0.1 local-dev.livedomain.com
# </FRONT-PROXY-HOSTS>

停止代理（按 Ctrl+C）时会移除该区块，除非启动时使用了 --persist-hosts。如果代理未正常停止（崩溃或被强制终止），该区块会一直保留，直到下次启动。每次启动都会用新的区块替换找到的任何现有区块。add 和 remove 只会更改配置，因此需要重启代理才能应用更改。

对于未配置的域名的请求会收到 502 响应。

主机名必须有效（由字母、数字、连字符和点组成，例如 myapp.local）。IP 地址、localhost、front-proxy.localhost 以及端口 80/443（代理自身使用的端口）均不允许使用。proxyHosts.json 中未通过这些检查的条目会被跳过，并显示警告。

管理页面

代理运行时，打开 http://front-proxy.localhost 即可在浏览器中管理域名。页面可以：

• 列出已配置的域名，并用圆点显示各端口是否有程序在监听
• 添加和移除域名，以及更改域名的端口
• 显示各域名使用的证书；若未配置证书，则显示可复制的 generate-certs 命令
• 提供各活动域名的 HTTP 链接（启用 HTTPS 时也提供 HTTPS 链接）

更改会像 CLI 命令一样立即保存到 proxyHosts.json。随后页面会显示提示横幅，直到更改生效：点击 立即应用，无需重启即可重新加载路由、证书和 /etc/hosts 区块；或者重启 front-proxy。

代理以 root 身份运行，因此页面仅接受：

• 来自本机（127.0.0.1/::1）且主机为 front-proxy.localhost 的请求，以阻止 LAN 客户端和 DNS 重绑定
• 由页面自身发送的更改：具有页面的 Origin、JSON 正文和每次代理启动时生成的随机令牌

页面的响应使用严格的内容安全策略，且不能被嵌入框架中。如需关闭页面，请使用 front-proxy --no-admin 启动。

若要通过 HTTPS 访问管理页面，默认证书必须包含 front-proxy.localhost。generate-certs 在创建默认证书时会将其添加进去。如果你的证书是由旧版本创建的，请删除 ~/.front-proxy/keys/_private-default-*.pem，然后重新运行 front-proxy generate-certs。

MCP 服务

front-proxy mcp 会通过 stdio 运行一个 Model Context Protocol 服务，让代码助手（Claude Code、Cursor、VS Code、Codex、Windsurf……）帮你管理域名。例如，它们可以将刚启动的应用映射到某个域名，并检查应用是否有响应。它已作为 io.github.gutomezencio/front-proxy 收录在 MCP 注册表中。

Claude Code：安装插件，它会添加 MCP 服务和一项技能，告诉 Claude 何时 front-proxy 能提供帮助（允许列表中的域名、CORS、Cookie、本地 HTTPS）：

claude plugin marketplace add gutomezencio/front-proxy
claude plugin install front-proxy@front-proxy

或者只添加 MCP 服务：claude mcp add front-proxy -- npx -y front-proxy mcp。

Claude Desktop：从最新版本下载 front-proxy.mcpb 并打开。

Codex：codex mcp add front-proxy -- npx -y front-proxy mcp。

其他客户端在其 MCP 配置中使用相同命令：

{
  "mcpServers": {
    "front-proxy": { "command": "npx", "args": ["-y", "front-proxy", "mcp"] }
  }
}

如果你全局安装了 front-proxy，也可以运行 front-proxy mcp。两者共用 ~/.front-proxy 中的配置，但代理本身仍从全局安装运行（见下文）。

工具	功能
list_hosts	列出已配置的域名、对应端口和证书状态
add_host	将域名映射到本地端口（执行与 front-proxy add 相同的检查）
update_host	将域名指向另一个端口
remove_host	移除域名
generate_certs	使用 mkcert 为一个或所有域名创建 HTTPS 证书
proxy_status	查看代理是否正在运行、HTTPS 是否已启用、是否有待应用的更改，以及哪些应用正在监听
apply_config	将保存的配置加载到运行中的代理中，类似于管理页面上的 立即应用

MCP 服务以你的身份运行，无需 sudo，与 add 和 remove 一样。所做的更改会保存到 proxyHosts.json。要应用这些更改，它会使用与管理页面相同的每次运行令牌和 Origin，通过 127.0.0.1 调用运行中代理的管理 API。以下操作需要你手动完成：

• 启动和停止代理需要你的密码，因此助手会提示你运行 front-proxy。
• apply_config 需要启用管理页面（默认启用）。使用 --no-admin 时，请重启代理以应用更改。
• generate_certs 无法输入你的密码，因此使用前请在终端中运行一次 mkcert -install。

HTTPS

端口 443 上的 HTTPS 需要本地受信任的证书，front-proxy 会通过 mkcert 创建这些证书：

front-proxy generate-certs                            # every configured domain
front-proxy generate-certs local-dev.livedomain.com   # a single domain

首次运行时会安装 mkcert 的本地 CA，以便浏览器信任这些证书。它还会为 localhost 和 front-proxy.localhost 创建默认证书。每个域名随后都会获得自己的证书，代理通过 SNI 提供这些证书。没有专属证书的域名会回退到默认证书。如果没有默认证书，代理将仅以 HTTP 启动。

如果为某个域名创建并应用证书后，Chrome 仍显示“不安全”，请完全退出 Chrome（macOS 上按 Cmd+Q）并重新打开。Chrome 会记住之前遇到过或你点击继续访问的证书错误，直到重启为止。只有在运行 generate-certs 之前安装了 nss（brew install nss），Firefox 才会信任 mkcert 的 CA。

HTTPS 响应包含 HSTS 标头（includeSubDomains、preload），因此浏览器会记住这些域名应使用 HTTPS。

自定义证书

要使用自己的证书（例如通配符证书），请将其保存到 ~/.front-proxy/keys/，命名为 _private-<name>-cert.pem 和 _private-<name>-key.pem，然后为每个要使用该证书的域名设置 "cert": "<name>"：

mkcert \
  -cert-file ~/.front-proxy/keys/_private-mydomain-cert.pem \
  -key-file  ~/.front-proxy/keys/_private-mydomain-key.pem \
  "*.mydomain.com"

配置

域名存储在 ~/.front-proxy/proxyHosts.json 中，证书存储在 ~/.front-proxy/keys/ 中。该文件夹会在首次运行时创建。若要将其存放在其他位置，请设置 FRONT_PROXY_HOME 环境变量。

上述命令会管理配置，但你也可以手动编辑：

{
  "local-dev.livedomain.com": {
    "port": 3000,
    "cert": "local-dev.livedomain.com"
  }
}

键	描述
port	域名代理到的本地端口，位于 127.0.0.1
cert	可选。指向 ~/.front-proxy/keys/_private-<cert>-{cert,key}.pem。多个域名可以共用一个证书

以 $ 开头的键（例如 CLI 写入的 $comment）会被忽略。

卸载

请先停止代理（按 Ctrl+C），以便移除其在 /etc/hosts 中的区块。如果你使用了 --persist-hosts，或者旧版本曾添加你的域名，请在不带此标志的情况下启动代理一次，然后停止它以清理这些条目：

front-proxy                        # then Ctrl+C
npm uninstall -g front-proxy
rm -rf ~/.front-proxy              # config and certificates
mkcert -uninstall                  # optional: remove mkcert's local CA

开发

要从克隆的仓库中使用 front-proxy，或参与开发：

git clone [email protected]:gutomezencio/front-proxy.git
cd front-proxy
npm install
npm run build   # compile src/ (TypeScript) to dist/
npm link        # point the global `front-proxy` command at this clone

如果之前安装过 npm 包，请先运行 npm uninstall -g front-proxy，以免两者冲突。npm link 会将全局命令链接到克隆仓库的 dist/，因此请保留该文件夹，并运行 git pull 和 npm run build 进行更新。npm unlink -g front-proxy 会移除该链接。克隆仓库与 npm 包使用相同的 ~/.front-proxy 配置。

npm run build                # compile src/ to dist/ and copy the admin page's static files
npm start                    # build, then run the proxy from dist/, without the sudo wrapper
npm run dev                  # same, rebuilding and restarting on file changes
npm run start:root -- list   # build, then run through the sudo wrapper, like the installed CLI
npm run typecheck            # type-check src/ and test/
npm test                     # run the tests (Jest with ts-jest, straight from src/)
npm run test:coverage        # same, with coverage (fails below the thresholds in package.json)
npm pack --dry-run           # list the files that get published to npm
npm run build:mcpb           # build front-proxy.mcpb, the Claude Desktop bundle

代码使用 TypeScript（严格模式、原生 ES 模块），并使用 zod 模式验证所有内容。tsc 会将代码编译到 dist/，而 npm pack/npm publish 会先构建代码（通过 prepack 脚本）。发布内容仅包括 dist/、README.md、LICENSE 和 package.json（由 package.json 中的 files 字段指定）。

许可证

MIT