概览
目标: 将开发代理与适用于 Linux 的 Windows 子系统配合使用(WSL)
时间: 15 分钟
先决条件:设置开发代理,安装 WSL
在 WSL(适用于 Linux 的 Windows 子系统)中开发应用程序时,有两种使用开发代理的选项:在 Windows 主机或 WSL 中运行它。 这两种方法都有其优势,具体取决于开发工作流。
选项 1:Windows 主机上的开发代理(建议)
最简单的方法是在 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 上设置开发代理
使用 winget 或手动安装在 Windows 上安装开发代理。
启动开发代理:
devproxy在提示时信任证书。
从 WSL 使用开发代理
当开发代理作为系统代理在 Windows 上运行(默认行为),并且你配置了 WSL 网络时,WSL 中的应用程序会自动通过它路由其流量。
像平常一样在 WSL 中启动应用程序。 开发代理会拦截那些遵循代理设置的应用程序所发出的 HTTPS 请求。
重要
启动或停止开发代理后重启 WSL
WSL 在启动时读取Windows代理设置。 如果在 WSL 正在运行后启动开发代理,或者停止并重启开发代理,则需要重启 WSL 才能使更改生效:
wsl --shutdown
然后启动新的 WSL 会话。
信任 WSL 中的证书
若要让开发代理截获 HTTPS 流量,WSL 中的应用程序需要信任开发代理证书。 可以从 Windows 复制证书或使用开发代理 API 导出证书。
选项 A:从 Windows 复制证书
在 WSL 中,从 Windows 复制证书:
cp "/mnt/c/Users/<your-username>/AppData/Local/Programs/Dev Proxy/rootCert.pfx" ~/导出并安装证书:
# 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 没有图形桌面环境,因此开发代理无法自动注册为系统代理。 将应用程序配置为手动使用代理。
创建一个 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" }启动开发代理:
devproxy信任证书:
# 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将应用程序配置为使用代理。
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 的请求:
验证
networkingMode=mirrored和.wslconfig是否已在autoProxy=true文件的[wsl2]节中设置。 有关详细信息,请参阅 配置 WSL 网络。重启 WSL 以刷新代理设置:
wsl --shutdown验证 Dev Proxy 是否正在运行并注册为系统代理。
检查开发代理证书是否在 WSL 中受信任。
unzip: 命令未找到
如果安装脚本因 unzip: command not found 错误而失败,请安装 unzip,然后再次运行安装脚本:
sudo apt update
sudo apt install unzip
证书错误
如果看到证书错误:
- 确保按照 WSL 中的“信任证书”中的步骤在 WSL 中安装证书。
- 对于 Node.js 应用程序,您可能需要将应用程序配置为使用代理服务器。 请参阅 将开发代理用于 Node.js 应用程序。
WSL 网络问题
WSL 2 使用虚拟化网络适配器。 如果遇到网络问题:
- 确保 Windows 防火墙允许开发代理。
- 尝试使用
localhost,而不是127.0.0.1在配置代理地址时使用。