概览
目标:在开发容器或 GitHub Codespaces 中安装 Dev Proxy
时间: 10 分钟
先决条件:包含devcontainer.json文件的项目、Docker 或 GitHub Codespaces
如果在开发容器或GitHub Codespaces中开发,则可以使用 Dev Proxy Dev Container Feature 安装 Dev Proxy。 该功能在容器中安装开发代理,并在创建容器后生成容器唯一的开发代理根证书并信任它。 无需按照 首次运行步骤 自行信任证书。
将 Dev Proxy 功能添加到开发容器
若要在开发容器中安装 Dev Proxy,请将 Dev Proxy 功能添加到 .devcontainer/devcontainer.json 文件的 features 部分:
{
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
"features": {
"ghcr.io/dotnet/dev-proxy/dev-proxy:1": {}
}
}
重新生成容器或创建新的代码空间以应用更改。 容器启动后,验证是否已安装 Dev Proxy:
devproxy --version
注意
该功能独立于 Dev Proxy 进行版本控制。
ghcr.io/dotnet/dev-proxy/dev-proxy:1 是指该功能的版本 1。 若要选择要安装的 Dev Proxy 版本,请使用 version 此选项。
配置该功能
此功能支持以下选项:
| 选项 | Description | 类型 | 默认 |
|---|---|---|---|
version |
要安装的 Dev Proxy 版本:latest、beta或特定版本,例如 4.0.0 或 v4.0.0。 |
字符串 | latest |
trustCertificate |
创建容器后,生成容器专用的开发代理根证书,并将其设为系统范围受信任,同时使常见运行时也信任它。 | boolean | true |
例如,若要安装特定版本的 Dev Proxy,请使用以下配置:
{
"features": {
"ghcr.io/dotnet/dev-proxy/dev-proxy:1": {
"version": "4.0.0"
}
}
}
若要尝试最新的预览功能,请将 version 设置为 beta。 安装 beta 版本时,该功能还会添加 devproxy-beta 命令。
如果在共享开发容器配置中使用 Dev Proxy,请考虑将 Dev Proxy 固定到特定版本,而不是 latest 或 beta。 这样,可确保处理项目的每个人都使用相同版本的 Dev Proxy。
功能如何处理根证书
开发代理使用根证书解密 HTTPS 流量。 生成映像时,该功能不会生成证书。 如果确实如此,证书及其私钥最终将出现在映像层中,并且使用同一映像或 Codespaces 预构建的每个人都会共享相同的受信任 CA 证书。
相反,在创建容器后 (postCreateCommand),该功能:
- 以远程用户身份运行
devproxy cert ensure,以生成该容器专有的根证书。 - 将证书添加到系统证书存储(
/usr/local/share/ca-certificates),以便 curl、.NET 和其他使用系统存储的工具信任它。
某些运行时不使用系统证书存储,因此功能会设置以下环境变量,使其指向系统 CA 捆绑包(/etc/ssl/certs/ca-certificates.crt):
| 可变 | 使用者 |
|---|---|
NODE_EXTRA_CA_CERTS |
Node.js |
REQUESTS_CA_BUNDLE |
Python requests |
SSL_CERT_FILE |
Python和其他基于 OpenSSL 的工具 |
为了信任证书,该功能会安装一个归 root 所有的帮助程序脚本,并允许远程用户在不使用密码的情况下使用 sudo 运行它。 如果不希望该功能生成并信任证书,请将trustCertificate设置为false:
{
"features": {
"ghcr.io/dotnet/dev-proxy/dev-proxy:1": {
"trustCertificate": false
}
}
}
重要
此功能不会配置Java密钥存储,因此Java应用不信任开发代理根证书。
Python 3.13 及更新版本启用严格的证书验证,这将拒绝 Dev Proxy v3 及更早版本为截获的主机生成的证书。 若要从 Python 3.13 或更高版本通过 Dev Proxy 调用 API,请使用 Dev Proxy v4 或更高版本。
在开发容器中使用 Dev Proxy
该功能不会启动开发代理,也不会为整个容器设置 HTTP_PROXY 或 HTTPS_PROXY 环境变量。 容器范围的代理变量将通过开发代理路由包管理器、git 和 VS Code 自己的流量,这会在开发代理未运行时中断它们。
若要使用 Dev Proxy,请使用配置文件在开发容器的终端中启动它:
devproxy --config-file .devproxy/devproxyrc.json
然后,配置要测试的应用以使用 Dev Proxy。 例如,若要通过开发代理从 Node.js 应用路由请求,请使用 HTTPS_PROXY 环境变量启动应用:
HTTPS_PROXY=http://127.0.0.1:8000 npm start
有关将应用配置为使用 Dev Proxy 的详细信息,请参阅适用于您的堆栈的指南,例如 将 Dev Proxy 与 Node.js 应用程序配合使用 或 将 Dev Proxy 用于 .NET 应用程序。
开发者代理工具包
此功能将 Dev Proxy Toolkit 扩展添加到开发容器内的 VS Code 中。 如果不想安装扩展,请在你的devcontainer.json文件中排除它:
{
"features": {
"ghcr.io/dotnet/dev-proxy/dev-proxy:1": {}
},
"customizations": {
"vscode": {
"extensions": ["-garrytrinder.dev-proxy-toolkit"]
}
}
}
支持的图像
此功能支持 x64 和 arm64 上的基于 Debian 和 Ubuntu 的映像。 不支持 Alpine 和其他基于 musl 的镜像。