# Network Extension

> 使用 Proxyman 的 Network Extension 抓取 Mac 上所有应用的 HTTP 和 HTTPS 流量，包括忽略系统代理设置的应用和脚本。

## 1. 这是什么？ {#1-whats-it}

Network Extension 可以抓取 Mac 上应用的 HTTP/HTTPS 流量，包括忽略系统代理的应用。

它基于 Apple 的[透明代理 Network Extension API](https://developer.apple.com/documentation/networkextension/netransparentproxyprovider) 构建，以 macOS 系统扩展的形式运行，使用我们的 TablePlus Inc Developer ID 证书签名，并已通过 Apple 公证。

其工作方式与 Fiddler Everywhere 中的 Network Capture 模式以及 mitmproxy 中的 Local Capture 模式类似。你无需在每个应用中单独设置代理。

> **注意:** Network Extension 目前为 BETA 版，默认关闭。它需要 Proxyman PRO（官网直接下载版）和 macOS 26 或更高版本。Setapp 中不提供该功能。

![Proxyman 无需 --proxy 参数即可抓取 cURL 的 HTTPS 请求](https://proxyman.com/docs/assets/proxyman_network_extension.jpeg)

_无需 --proxy 参数即可抓取 cURL 请求_

## 2. 存在的问题 {#2-problem}

常规代理模式依赖应用将请求发送到代理。

* 部分应用和脚本会忽略 macOS 的系统代理，因此 Proxyman 无法捕获它们的请求。
* NodeJS、Ruby 和 Python 库可能需要单独设置代理、修改代码，或使用 Automatic Setup。
* 逐个手动配置每个应用或库既费时，又容易出错。

## 3. 优势 {#3-benefits}

* 抓取忽略代理设置的应用和脚本的流量。
* 无需为每个应用手动设置代理。
* 可对抓取到的请求使用 Map Local、Breakpoint、Scripting 等现有工具。

## 4. 如何安装 Network Extension？ {#4-how-to-install-the-network-extension}

1. 通过以下两种方式之一开启 Network Extension：

* 打开 Proxyman -> **Settings** -> **Network Extension**，开启 **Enable Network Extension**。如果出现提示，请点击 **Install and Enable**。

![Proxyman Settings 中的 Network Extension 面板及 Enable Network Extension 开关](https://proxyman.com/docs/assets/Screenshot%202026-10-01%20at%2019.56.42.jpg)

_在 Settings 中开启 Network Extension_

* 或者点击主窗口顶部的状态栏（Proxyman | Listening on ...），然后开启 **Network Extension**。

2. 打开 **System Settings** -> **General** -> **Login Items & Extensions**。在 **Extensions** 下，选择 **By Category** -> **Network Extensions**，然后启用 Proxyman。
3. 当 macOS 询问是否添加网络配置时，点击 **Allow**。

![在 Network Extensions 中开启 Proxyman 开关](https://proxyman.com/docs/assets/install_proxyman_network_extension_step_2.jpeg)

_允许 Proxyman Network Extension_

4. 等待 Proxyman 显示 “Capturing HTTP and HTTPS from local applications.”

## 5. 如何使用？ {#5-how-to-use}

1. 保持 Proxyman 开启，并启用 Network Extension。
2. 此时 Network Extension 会抓取 Mac 上应用的流量，并将其发送给 Proxyman。
3. 如需查看 HTTPS 内容，请先[安装并信任 Proxyman 证书](https://proxyman.com/docs/zh-cn/debug-devices/macos)，然后为相应应用或域名启用 [SSL Proxying](https://proxyman.com/docs/zh-cn/basic-features/ssl-proxying)。
4. 从应用、浏览器或脚本发起新请求，该请求会显示在 Proxyman 中。

如果应用在启用扩展之前就已运行，请重启该应用，以便捕获新的连接。

如果只想停止抓取而不卸载，请在 Settings 中关闭 **Enable Network Extension**。

## 6. 故障排查 {#6-troubleshooting}

### NodeJS、Ruby 或 Python 中的 SSL 错误 {#ssl-errors-in-nodejs-ruby-or-python}

即使你已在 macOS 中信任 Proxyman 的自签名证书，这些运行时环境也可能不信任该证书。Network Extension 会抓取它们的流量，但证书信任仍需单独设置。

对于支持的库，请使用 [Automatic Setup](https://proxyman.com/docs/zh-cn/automatic-setup/automatic-setup) 设置证书信任：

1. 打开 Proxyman -> **Setup** -> **Automatic Setup**。
2. 点击 **Open New Terminal**，如有需要，请接受权限提示。
3. 在新打开的终端中运行脚本，或重启服务器。

> **提示:** 如果你正在使用 [Automatic Setup](https://proxyman.com/docs/zh-cn/automatic-setup/automatic-setup) 或 [Manual Setup](https://proxyman.com/docs/zh-cn/automatic-setup/manual-setup)，可以在 **Settings** -> **Network Extension** 中关闭 **Enable Network Extension**。请继续在该设置所配置的终端中运行脚本或服务器。

如果错误仍然存在，请查看 [Automatic Setup 故障排查指南](https://proxyman.com/docs/zh-cn/automatic-setup/troubleshooting)。

## 7. 如何卸载 Network Extension？ {#7-how-to-uninstall-the-network-extension}

1. 打开 Proxyman -> **Settings** -> **Network Extension**。
2. 点击 **Uninstall**，然后确认。
3. 如系统要求，请输入 Mac 密码；如有提示，请重启 Mac。

卸载会停止抓取，并关闭正在使用该扩展的连接。同时还会删除网络配置。

## 8. 命令行 {#8-command-line}

使用 `proxyman-cli network-extension` 可以查看状态、安装、卸载、启用、禁用或重试。运行时需保持 Proxyman 处于打开状态。使用 `install` 可在不开启抓取的情况下安装扩展；使用 `enable` 则可开启抓取，并在需要时安装扩展。可能仍需要在 macOS 中进行批准，或重启 Mac。

有关命令、JSON 状态字段和退出码，请参阅 [Network Extension 命令行指南](https://proxyman.com/docs/zh-cn/command-line#16-network-extension)。

## 了解更多 {#learn-more}

* [介绍 Network Extension：无需设置代理即可抓取 Mac 流量](https://proxyman.com/posts/2026-10-06-introducing-network-extension)