将 Dev Proxy 与 WSL 配合使用

概览
目标: 将开发代理与适用于 Linux 的 Windows 子系统配合使用(WSL)
时间: 15 分钟
先决条件:设置开发代理,安装 WSL

在 WSL(适用于 Linux 的 Windows 子系统)中开发应用程序时,有两种使用开发代理的选项:在 Windows 主机或 WSL 中运行它。 这两种方法都有其优势,具体取决于开发工作流。

最简单的方法是在 Windows 上安装和运行开发代理。 借助 WSL 的自动代理和镜像网络模式,WSL 使用 Windows 系统代理,因此 WSL 中运行的应用程序的流量被 Dev Proxy 截获,而无需在 WSL 中配置代理。

配置 WSL 网络

开发代理会将自身注册为 localhost 地址上的 Windows 系统代理(默认为 127.0.0.1:8000)。 若要使 WSL 中的应用程序使用此代理,请在位于 Windows 上 [wsl2] 的 WSL 配置文件的 %UserProfile%\.wslconfig 部分中启用以下设置:

[wsl2]
networkingMode=mirrored
autoProxy=true
Setting Description
networkingMode=mirrored 将 Windows 网络接口镜像到 Linux 中,从而使 WSL 中的应用程序能够使用 127.0.0.1 连接到在 Windows 上运行的服务器,例如 Dev Proxy。 需要Windows 11版本 22H2 或更高版本。 默认值为 nat。
autoProxy=true 使 WSL 使用 Windows HTTP 代理设置,以便在 WSL 中自动设置Windows上配置的代理。 在Windows 11上可用。 默认启用。

更改 .wslconfig 文件后,重启 WSL,使更改生效:

wsl --shutdown

注释

在默认 NAT 网络模式下,WSL 中的应用程序无法使用 127.0.0.1 连接到 Windows 上的开发代理。 如果无法使用镜像网络模式,请改为在 WSL 中运行开发代理。 有关详细信息,请参阅 选项 2:WSL 中的开发代理。

有关详细信息,请参阅 使用 WSL 访问网络应用程序 和 WSL 中的高级设置配置。

在 Windows 上设置开发代理

  1. 使用 winget 或手动安装在 Windows 上安装开发代理。

  2. 启动开发代理:

    devproxy
    
  3. 在提示时信任证书。

从 WSL 使用开发代理

当开发代理作为系统代理在 Windows 上运行(默认行为),并且你配置了 WSL 网络时,WSL 中的应用程序会自动通过它路由其流量。

像平常一样在 WSL 中启动应用程序。 开发代理会拦截那些遵循代理设置的应用程序所发出的 HTTPS 请求。

重要

启动或停止开发代理后重启 WSL

WSL 在启动时读取Windows代理设置。 如果在 WSL 正在运行后启动开发代理,或者停止并重启开发代理,则需要重启 WSL 才能使更改生效:

wsl --shutdown

然后启动新的 WSL 会话。

信任 WSL 中的证书

若要让开发代理截获 HTTPS 流量,WSL 中的应用程序需要信任开发代理证书。 可以从 Windows 复制证书或使用开发代理 API 导出证书。

选项 A:从 Windows 复制证书

  1. 在 WSL 中,从 Windows 复制证书:

    cp "/mnt/c/Users/<your-username>/AppData/Local/Programs/Dev Proxy/rootCert.pfx" ~/
    
  2. 导出并安装证书:

    # Export the certificate
    openssl pkcs12 -in ~/rootCert.pfx -clcerts -nokeys -out dev-proxy-ca.crt -passin pass:""
    # Install the certificate
    sudo cp dev-proxy-ca.crt /usr/local/share/ca-certificates/
    # Update certificates
    sudo update-ca-certificates
    

选项 B:使用开发代理 API

开发代理 API 需要 Bearer 令牌。 当 Dev Proxy 在 Windows 上运行时,通过在 Windows 终端中运行 api token 命令来获取令牌:

devproxy api token

然后,在 WSL 中下载并安装证书。 将 <token> 替换为你检索到的令牌:

# Download the certificate from Dev Proxy API
curl -H "Authorization: Bearer <token>" -o dev-proxy-ca.crt "http://127.0.0.1:8897/proxy/rootCertificate?format=crt"
# Install the certificate
sudo cp dev-proxy-ca.crt /usr/local/share/ca-certificates/
# Update certificates
sudo update-ca-certificates

注释

某些应用程序可能需要额外的配置来信任系统证书存储。 对于 Node.js 应用程序,可能需要出于开发目的进行设置 NODE_TLS_REJECT_UNAUTHORIZED=0 。 不建议对生产代码禁用证书验证。

选项 2:WSL 中的开发代理

如果想要在 WSL 中完全运行开发代理,请使用 Linux 安装方法安装它并手动配置代理。

在 WSL 中安装开发代理

安装脚本需要 unzip 来提取开发代理。 默认情况下,新的 WSL 分发版(如 Ubuntu)不包含它。 安装 unzip:

sudo apt update
sudo apt install unzip

使用安装脚本安装开发代理:

bash -c "$(curl -sL https://aka.ms/devproxy/setup.sh)"

手动配置代理

由于 WSL 没有图形桌面环境,因此开发代理无法自动注册为系统代理。 将应用程序配置为手动使用代理。

  1. 创建一个 Dev Proxy 配置文件,其中 asSystemProxy 设置为 false:

    {
      "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/rc.schema.json",
      "asSystemProxy": false,
      "plugins": [
        {
          "name": "RetryAfterPlugin",
          "enabled": true,
          "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll"
        },
        {
          "name": "GenericRandomErrorPlugin",
          "enabled": true,
          "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
          "configSection": "genericRandomErrorPlugin"
        }
      ],
      "urlsToWatch": [
        "https://jsonplaceholder.typicode.com/*"
      ],
      "genericRandomErrorPlugin": {
        "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/genericrandomerrorplugin.schema.json",
        "errorsFile": "devproxy-errors.json",
        "rate": 50
      },
      "logLevel": "information"
    }
    
  2. 启动开发代理:

    devproxy
    
  3. 信任证书:

    # Export Dev Proxy root certificate
    openssl pkcs12 -in ~/.config/dev-proxy/rootCert.pfx -clcerts -nokeys -out dev-proxy-ca.crt -passin pass:""
    # Install the certificate
    sudo cp dev-proxy-ca.crt /usr/local/share/ca-certificates/
    # Update certificates
    sudo update-ca-certificates
    
  4. 将应用程序配置为使用代理。 HTTPS_PROXY设置环境变量:

    export HTTPS_PROXY=http://127.0.0.1:8000
    

    或在运行应用程序时指定它:

    HTTPS_PROXY=http://127.0.0.1:8000 node app.js
    

小窍门

有关为 Node.js 应用程序配置代理的详细信息,请参阅 将开发代理用于 Node.js 应用程序。

方法比较

功能 / 特点 Windows 主机 (选项 1) 在 WSL 内(选项 2)
配置复杂性 简单 中等
Requirements Windows 11 22H2 或更高版本,WSL 镜像网络模式 None
证书管理 从 Windows 进行一次性复制 手动导出
代理配置 自动 (WSL 自动代理) 手动 (HTTPS_PROXY)
需要 WSL 重启 是的,切换代理时 否
适用于所有 WSL 应用 是的 取决于应用代理支持

对于大多数方案,建议在 Windows 上运行开发代理(选项 1),因为它的简单性和自动代理配置。

故障排除

使用 Windows 主机时,请求不会被截获

如果 Windows 上的开发代理未截获来自 WSL 的请求:

  1. 验证 networkingMode=mirrored 和 .wslconfig 是否已在 autoProxy=true 文件的 [wsl2] 节中设置。 有关详细信息,请参阅 配置 WSL 网络。

  2. 重启 WSL 以刷新代理设置:

    wsl --shutdown
    
  3. 验证 Dev Proxy 是否正在运行并注册为系统代理。

  4. 检查开发代理证书是否在 WSL 中受信任。

unzip: 命令未找到

如果安装脚本因 unzip: command not found 错误而失败,请安装 unzip,然后再次运行安装脚本:

sudo apt update
sudo apt install unzip

证书错误

如果看到证书错误:

  1. 确保按照 WSL 中的“信任证书”中的步骤在 WSL 中安装证书。
  2. 对于 Node.js 应用程序,您可能需要将应用程序配置为使用代理服务器。 请参阅 将开发代理用于 Node.js 应用程序。

WSL 网络问题

WSL 2 使用虚拟化网络适配器。 如果遇到网络问题:

  1. 确保 Windows 防火墙允许开发代理。
  2. 尝试使用 localhost ,而不是 127.0.0.1 在配置代理地址时使用。