Charles Proxy

Charles Proxy 作为中间人代理运行，捕获客户端应用与目标服务器之间的全部网络流量并允许检查和修改，从而简化 HTTP 请求的调试。

Charles Proxy 以本地 HTTP 代理服务器的形式运行，使开发者和 QA 工程师能够观察、拦截并操作网络通信。这一能力对于理解客户端与服务器的交互、诊断集成问题、测试边界情况以及验证 API 行为至关重要，尤其是在使用或开发与上游代理交互的服务时。

配置 Charles Proxy

安装与首次启动

从官方网站下载并安装 Charles Proxy。首次启动时，Charles 通常会尝试将自身设置为系统代理。接受该提示，让 Charles 能够拦截遵循系统代理设置的应用流量。

配置系统代理设置

Charles 运行时会自动将系统的 HTTP/HTTPS 代理设置为 127.0.0.1（localhost）的 8888 端口（默认）。包括网页浏览器在内的大多数应用都会遵循这些设置。

如需验证或手动配置：
* macOS： 系统设置 > 网络 > Wi-Fi/以太网 > 详细信息 > 代理。确认已启用 "Web Proxy (HTTP)" 和 "Secure Web Proxy (HTTPS)" 并指向 127.0.0.1:8888。
* Windows： 设置 > 网络和 Internet > 代理 > 手动设置代理。确认已启用"使用代理服务器"，地址为 127.0.0.1，端口为 8888。
* Linux（GNOME）： 设置 > 网络 > 网络代理。将方式设为"手动"，并将 HTTP/HTTPS 代理配置为 127.0.0.1:8888。

配置客户端应用

某些应用，特别是命令行工具或特定 SDK，可能不遵循系统级代理设置。这种情况下需要直接配置该应用。

示例：使用代理的 curl

curl -x http://127.0.0.1:8888 https://api.example.com/data

示例：使用代理的 Node.js axios

const axios = require('axios');

axios.get('https://api.example.com/data', {
  proxy: {
    host: '127.0.0.1',
    port: 8888
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

HTTPS 流量的 SSL Proxying

要检查 HTTPS 流量，Charles Proxy 必须执行 SSL（或 TLS）代理。这需要 Charles 为目标域名生成并签发证书、将其提供给客户端，然后与真实服务器建立自己的安全连接。

安装 Charles 根证书

客户端应用必须信任 Charles 的根证书，SSL 代理才能在没有安全警告的情况下工作。

• 桌面浏览器/系统：
  • 进入 Help > SSL Proxying > Install Charles Root Certificate。按照操作系统的具体提示，将其安装到系统的受信任根证书存储中。
• 移动设备：
  • 将移动设备配置为使用 Charles 作为 HTTP 代理（例如 your_mac_ip:8888）。
  • 在设备上访问 chls.pro/ssl，按照说明下载并安装证书。

为特定主机启用 SSL Proxying

安装根证书后，为你想要检查的特定主机启用 SSL 代理。

1. 进入 Proxy > SSL Proxying Settings...。
2. 点击 "Add"。
3. 输入 Host（例如 api.example.com、通配符 *.example.com，或代表全部主机的 *）和 Port（HTTPS 通常为 443，全部端口用 *）。
4. 点击 "OK"，然后再次点击 "OK"。

指定主机的流量此时会被解密并在 Charles 中可见。

主要调试功能

流量监控与过滤

"Structure" 和 "Sequence" 视图显示已捕获的请求。
* Sequence 视图： 按时间顺序显示请求。
* Structure 视图： 按主机和路径组织请求。

聚焦相关流量的方法：
* 过滤字段： 使用 Charles 窗口顶部的过滤字段匹配 URL、主机或内容。
* Focus 工具： 右键点击某个请求并选择 "Focus"，即可在当前视图中隐藏其他所有主机。
* 录制按钮： 切换录制按钮（红色圆点）以开始/停止捕获流量。

断点

断点让你可以在请求发送到服务器之前、或响应送达客户端之前将其暂停并修改。

1. 进入 Proxy > Breakpoints Settings...。
2. 为请求或响应点击 "Add"。
3. 指定 Host 和 Path（例如 /login）。
4. 当请求/响应匹配时，Charles 会暂停，并出现 "Breakpoints" 标签页。
5. 修改请求头、查询参数或正文。
6. 点击 "Execute" 发送修改后的请求/响应。

Rewrite 工具

Rewrite 工具可对请求和响应进行自动且持久的修改。它适合在无需人工干预的情况下模拟特定的服务器行为或客户端条件。

1. 进入 Tools > Rewrite...。
2. 启用 Rewrite 并添加一个新的 "Set"。
3. 使用 Host 和 Path 添加 "Locations"（规则适用的 URL）。
4. 在该 set 中添加 "Rules"：
   • Add Header/Remove Header： 修改 HTTP 请求头。
   • Change Query Parameter： 修改 URL 查询参数。
   • Body Replace： 在请求/响应正文中查找并替换文本。
   • URL Replace： 修改请求 URL 的部分内容。

示例：修改 API 响应正文
一条 Rewrite 规则可以把 JSON 响应中的 {"status": "active"} 替换为 {"status": "maintenance"}，以测试客户端如何处理不同状态。

Map Local / Map Remote

这些工具会把请求重定向到不同的来源。

• Map Local： 用本地文件替代远程响应。

  1. 进入 Tools > Map Local...。
  2. 启用 Map Local 并添加一条新条目。
  3. 指定远程 URL 的 Host 和 Path。
  4. 选择要提供的本地 File 路径。
     这适合在不修改后端的情况下快速测试 UI 变更或模拟特定 API 响应。

• Map Remote： 将对某个 URL 的请求重定向到完全不同的 URL。

  1. 进入 Tools > Map Remote...。
  2. 启用 Map Remote 并添加一条新条目。
  3. 指定原始请求的 Host 和 Path。
  4. 为重定向后的请求指定新的 Host 和 Path。
     适合将 API 调用重定向到预发布环境或本地开发服务器。

限速（Throttling）

限速可模拟慢速网络条件，帮助识别性能瓶颈或与数据加载缓慢相关的 UI 问题。

1. 进入 Proxy > Throttle Settings...。
2. 启用 "Enable Throttling"。
3. 配置 Bandwidth、Utilisation 和 Latency 参数。
4. 可选：选择 "Only for selected hosts" 并添加需要限速的特定主机。

Repeat / Advanced Repeat

这些功能允许重新发送请求。

• Repeat： 右键点击某个请求并选择 "Repeat"，立即再次发送。
• Advanced Repeat： 右键点击某个请求并选择 "Advanced Repeat"，可用自定义并发数和迭代次数多次发送。这适合负载测试或检查竞态条件。

调试上游代理交互

当你的客户端应用配置为使用 Charles，而 Charles 自身又配置为使用上游代理（例如企业代理）时，Charles 充当中间环节。

将 Charles 配置为使用上游代理：
1. 进入 Proxy > External Proxy Settings...。
2. 启用 "Use external proxy"。
3. 输入上游代理的 Host、Port 以及所需的 Username/Password。
4. 若上游代理是 SOCKS 代理，请启用 "SOCKS proxy"。

在这种配置下，Charles 先捕获客户端流量，再转发给上游代理。这样你就能在流量到达上游代理之前进行检查，对于诊断上游代理可能修改请求或阻断某些端点的问题至关重要。

常见问题与排查

| 问题 | Charles Proxy 中的解决方案 CHARLES PROXY：通过代理调试 HTTP 请求

Charles Proxy 作为中间人代理运行，捕获客户端应用与目标服务器之间的全部网络流量，从而调试 HTTP 请求，并支持详细的检查与修改。

概述

Charles Proxy 是运行在本地机器上的 HTTP 代理（HTTP/HTTPS/SOCKS）和 HTTP 监控工具。它让你可以查看本机与互联网之间的全部 HTTP 和 HTTPS 流量。在调试与上游代理交互的服务时，可以把 Charles 配置在客户端与上游代理之间，从而清楚看到应用实际发送和接收的请求。

初始设置

安装

从官方网站（charlesproxy.com）下载并安装 Charles Proxy。Charles 支持 macOS、Windows 和 Linux。

系统代理配置

启动时，Charles 通常会提示将自身设置为系统代理。接受该提示后，Charles 可自动拦截配置为使用系统代理设置的应用流量（例如大多数网页浏览器、Java 应用、.NET 应用）。

手动验证或配置：
* 默认 HTTP/HTTPS 代理地址： 127.0.0.1
* 默认 HTTP/HTTPS 代理端口： 8888

若环境中 Charles 需要连接外部（上游）代理：
1. 进入 Proxy > External Proxy Settings...。
2. 勾选 "Use external proxy"。
3. 输入上游代理的 Host 和 Port。
4. 若上游代理需要，请填写 Username 和 Password。
5. 若上游代理是 SOCKS 代理，请勾选 "SOCKS proxy"。

该配置可确保 Charles 先捕获客户端流量，再通过指定的外部代理转发，使你能够检查发送到外部代理以及从其接收的内容。

HTTPS 流量的 SSL Proxying

HTTP Secure（HTTPS）流量是加密的，无法直接检查。Charles 采用 SSL Proxying（中间人攻击）来解密并检查 HTTPS 流量。

Charles 根证书安装

为执行 SSL Proxying，Charles 会为每个 HTTPS 域名动态生成 SSL 证书。你的客户端应用必须信任 Charles 的根证书，才能避免 SSL 错误。

• 桌面操作系统（macOS/Windows/Linux）：
  1. 进入 Help > SSL Proxying > Install Charles Root Certificate。
  2. 按照操作系统的提示，将证书安装到受信任根证书存储中。
• 移动设备（iOS/Android）：
  1. 将移动设备的 Wi-Fi 设置配置为使用 Charles 作为 HTTP 代理（Charles 的 IP 地址和 8888 端口）。
  2. 在移动设备上打开浏览器并访问 chls.pro/ssl。
  3. 按照说明下载并将 Charles 根证书安装为受信任凭据。

为特定主机启用 SSL Proxying

安装根证书后，指定 Charles 应解密哪些 HTTPS 主机。
1. 进入 Proxy > SSL Proxying Settings...。
2. 点击 "Add"。
3. 输入 Host（例如 api.yourdomain.com、*.yourdomain.com，或代表全部主机的 *）和 Port（通常为 443，全部端口用 *）。
4. 点击 "OK"。

核心调试功能

流量捕获与过滤

Charles 通过两个主要视图显示已捕获的流量：
* Sequence： 请求的时间顺序列表。
* Structure： 按主机和文件夹路径分组的层级视图。

定位特定请求：
* 过滤字段： 使用顶部的过滤栏按主机、URL 路径或内容搜索。
* Focus 工具： 右键点击某个请求并选择 "Focus"，即可在当前视图中隐藏其他所有主机。
* 录制按钮： 切换红色圆点图标以开始/停止捕获流量。

断点

断点允许在请求发送前、或响应到达客户端前进行手动拦截和修改。

1. 进入 Proxy > Breakpoints Settings...。
2. 为 "Request" 或 "Response" 断点点击 "Add"。
3. 为目标 URL 指定 Host 和 Path 匹配模式。
4. 当出现匹配的请求/响应时，Charles 会暂停并显示 "Breakpoints" 标签页。
5. 修改 Headers、Query Parameters 或 Body 内容。
6. 点击 "Execute" 以按修改后的内容继续该事务。

Rewrite 工具

Rewrite 工具依据预定义规则自动修改请求和响应。它适合在无需人工干预的情况下开展一致的测试场景。

1. 进入 Tools > Rewrite...。
2. 启用 Rewrite 并添加一个新的 "Set"。
3. 使用 Host 和 Path 定义 "Locations"（规则生效的 URL）。
4. 在该 set 中添加 "Rules"：
   • Type： Add Header、Remove Header、Change Query Parameter、Host、Path、URL、Body。
   • Action： 为修改指定 Value 或 Regex。

示例：模拟 API 版本变更
一条 Rewrite 规则可以把发往特定 API 端点的所有请求中的 Accept 请求头从 application/json;v=1 改为 application/json;v=2。

Map Local / Map Remote

这些功能会把请求重定向到替代资源。

• Map Local： 用本地文件替代远程服务器响应。

  1. 进入 Tools > Map Local...。
  2. 启用 Map Local 并添加一条新条目。
  3. 指定要映射的远程 URL 的 Host 和 Path。
  4. 选择 Charles 应提供的文件的 Local Path。
     这在前端开发中很有用，可在不修改后端的情况下用特定模拟数据测试 UI 变更。

• Map Remote： 将某个 URL 的请求重定向到完全不同的 URL。

  1. 进入 Tools > Map Remote...。
  2. 启用 Map Remote 并添加一条新条目。
  3. 指定原始请求的 Host 和 Path。
  4. 指定新目标 URL 的 Host 和 Path。
     这适合把生产环境的 API 调用重定向到预发布环境或本地开发服务器。

限速（Throttling）

限速可模拟各种网络条件（例如拨号、3G、自定义速度），用于测试应用在较差网络连接下的性能与响应能力。

1. 进入 Proxy > Throttle Settings...。
2. 勾选 "Enable Throttling"。
3. 选择一个 Preset，或手动配置 Bandwidth、Utilisation 和 Latency。
4. 可选：勾选 "Only for selected hosts" 并添加需要限速的特定主机。

Repeat / Advanced Repeat

这些功能允许重新发送请求。
* Repeat： 在 Charles 会话中右键点击某个请求并选择 "Repeat"，即可重新发送一次。
* Advanced Repeat： 右键点击某个请求并选择 "Advanced Repeat"，可配置多次重复、并发和延迟，适合基础负载测试或验证幂等性。

常见场景排查

| 问题 | 解决方案