VSCode 设置 HTTP/HTTPS 代理分步指南

2025-4-15

Visual Studio Code 设置 HTTP/HTTPS 代理终极分步指南

Visual Studio Code (VS Code) 作为当今最受欢迎的源代码编辑器之一，以其轻量、强大、高度可扩展的特性赢得了全球开发者的青睐。然而，VS Code 的许多核心功能和扩展（如扩展市场浏览/安装、自动更新、Git 集成、远程开发、语言服务器通信等）都依赖于网络连接。在某些网络环境（如企业内网、学校实验室或需要通过特定网关访问互联网的场景）中，直接访问外部网络资源可能会受到限制，此时通常需要配置 HTTP 或 HTTPS 代理服务器才能正常访问。

本文将为您提供一份详尽的分步指南，涵盖在 VS Code 中设置 HTTP/HTTPS 代理的各种方法、注意事项、验证步骤以及常见问题排查，帮助您在受限网络环境中也能顺畅地使用 VS Code 的全部功能。

为什么要配置 VS Code 代理？

在深入配置步骤之前，让我们先理解为什么需要进行这项设置：

突破网络限制： 最常见的原因是您所在的网络环境（例如公司防火墙、校园网）要求所有出站 HTTP/HTTPS 流量必须通过指定的代理服务器。不配置代理，VS Code 将无法访问扩展市场、下载更新、连接到远程仓库（如 GitHub）等。
访问特定资源： 有些资源可能只对特定区域或通过特定网络路径（由代理提供）开放。
安全与合规： 企业网络通常出于安全审计和策略执行的目的，强制所有流量通过代理。
匿名或IP地址变更： 在某些情况下，开发者可能需要通过代理隐藏真实 IP 地址或模拟不同地理位置的访问。

准备工作：获取代理服务器信息

在开始配置之前，您必须获取以下必要的代理服务器信息。通常，这些信息可以从您的网络管理员、IT 部门或代理服务提供商处获得：

代理服务器地址 (Hostname or IP Address): 例如 proxy.mycompany.com 或 192.168.1.100。
代理服务器端口 (Port Number): 例如 8080、3128 等。
代理类型: 明确是 HTTP 代理还是 HTTPS 代理，或者两者使用同一个地址。
认证信息 (可选): 如果代理服务器需要身份验证，您还需要获取：
- 用户名 (Username)
- 密码 (Password)

请务必确保您获取的信息准确无误，这是成功配置的关键。

配置 VS Code 代理：多种方法详解

VS Code 提供了多种配置代理的方式，您可以根据自己的需求和偏好选择最合适的一种。这些方法主要包括：

通过 VS Code 设置界面 (Settings UI)
直接编辑 settings.json 文件
使用环境变量 (Environment Variables)

下面我们将详细介绍每种方法的步骤。

方法一：通过 VS Code 设置界面 (推荐给初学者)

这是最直观、用户友好的方式，无需直接编辑配置文件。

步骤：

打开设置:
- 在 Windows/Linux 上，点击左下角的齿轮图标 (Manage)，然后选择 "Settings"，或者使用快捷键 Ctrl + ,。
- 在 macOS 上，点击菜单栏的 "Code" -> "Preferences" -> "Settings"，或者使用快捷键 Cmd + ,。
搜索代理设置:
- 在设置页面的顶部搜索框中，输入 proxy。这将筛选出与代理相关的设置项。
配置 HTTP 代理:
- 找到名为 Http: Proxy (http.proxy) 的设置项。
- 在其下方的输入框中，填入您的 HTTP 代理服务器地址和端口，格式为 http://<代理服务器地址>:<端口号>。
  - 示例 (无认证): http://proxy.mycompany.com:8080 或 http://192.168.1.100:3128
  - 示例 (需要认证): http://<用户名>:<密码>@<代理服务器地址>:<端口号>
    - 注意: 将 <用户名> 和 <密码> 替换为您的实际凭据。例如：http://user123:passwordABC@proxy.mycompany.com:8080。
    - 安全警告: 在设置界面或 settings.json 中直接存储明文密码存在安全风险，特别是如果您的设置文件被同步或共享。稍后我们会讨论更安全的替代方案。
配置 HTTPS 代理 (如果需要且与HTTP代理不同):
- 通常情况下，HTTPS 流量也会通过 http.proxy 设置的代理服务器。但如果您的 HTTPS 流量需要通过不同的代理服务器（或者您的 HTTP 代理不支持 CONNECT 方法处理 HTTPS 流量，虽然这种情况较少见），您可以单独配置 Https: Proxy (https.proxy) 设置项。
- 其格式与 http.proxy 类似，但协议头应根据代理服务器本身是否使用 HTTPS 来决定（通常代理服务器本身是 HTTP 的，即使它代理的是 HTTPS 流量）。大多数情况下，您会使用与 http.proxy 相同的设置，或者如果您的代理服务器支持，也可能使用 https://... 格式（但这非常罕见，请咨询您的网络管理员）。
- 常见做法: 如果 HTTP 和 HTTPS 使用同一个代理，通常只需要设置 http.proxy 即可。VS Code 会默认将此设置也用于 HTTPS 连接。如果 https.proxy 未设置，则自动使用 http.proxy 的值。只有在两者确实需要不同代理时才需要分别设置。
代理严格 SSL 检查 (可选但重要):
- 找到 Http: Proxy Strict SSL (http.proxyStrictSSL) 设置项。这是一个布尔值（勾选框）。
- 默认情况下，此项是启用的 (true)。这意味着 VS Code 会验证代理服务器提供的 SSL/TLS 证书的有效性。
- 在某些企业环境中，代理服务器可能会使用自签名证书或进行 SSL/TLS 解密与重新加密（中间人代理）。在这种情况下，启用严格 SSL 检查会导致连接失败。
- 如果遇到 SSL 相关的错误（例如 certificate signed by unknown authority, self signed certificate in certificate chain），您可以尝试取消勾选此项（将其设置为 false）。
- 安全警告: 禁用此选项会降低安全性，因为 VS Code 将不再验证代理服务器证书的真实性，增加了遭受中间人攻击的风险。请仅在确认网络环境安全且确实需要时才禁用它。
配置不使用代理的地址 (No Proxy):
- 找到 Http: No Proxy (http.noProxy) 设置项。
- 如果您希望某些特定的域名或 IP 地址不通过代理服务器访问（例如内部资源、本地开发服务器），可以在这里添加它们。
- 这是一个以逗号分隔的列表，支持域名、IP 地址、CIDR 地址块以及通配符 (*)。
- 示例: localhost, 127.0.0.1, *.mycompany.local, 10.0.0.0/8
- 这将使得访问 localhost、127.0.0.1、任何以 .mycompany.local 结尾的域名以及 10.x.x.x 网段的地址时，不使用上面配置的代理。
选择设置范围 (User vs Workspace):
- 在设置界面的顶部，您会看到 "User" 和 "Workspace" 两个选项卡。
  - User Settings (用户设置): 应用于您在此计算机上使用的所有 VS Code 实例和项目。这是最常用的选择，适用于全局代理配置。
  - Workspace Settings (工作区设置): 仅应用于当前打开的项目（工作区）。这些设置保存在项目根目录下的 .vscode/settings.json 文件中。适用于特定项目需要不同代理配置的情况。
- 根据您的需求选择合适的范围进行配置。通常建议在 "User" 级别配置全局代理。
保存设置: VS Code 的设置通常是自动保存的。更改后，设置应立即生效或在下次需要网络连接时生效。有时可能需要重启 VS Code 以确保所有进程都应用了新设置。

方法二：直接编辑 `settings.json` 文件

对于喜欢直接操作配置文件的开发者，或者需要进行更复杂配置（例如通过脚本自动化）的情况，可以直接编辑 settings.json 文件。

步骤：

打开 settings.json 文件:
- 按下 Ctrl + Shift + P (Windows/Linux) 或 Cmd + Shift + P (macOS) 打开命令面板 (Command Palette)。
- 输入 Preferences: Open User Settings (JSON) 并选择它，来编辑用户级别的设置。
- 或者，输入 Preferences: Open Workspace Settings (JSON) 并选择它，来编辑当前工作区级别的设置。

添加或修改代理配置:

在打开的 JSON 文件中，找到或添加以下键值对。确保它们位于最外层的大括号 {} 内，并遵循 JSON 语法规则（键和字符串值用双引号包裹，键值对之间用逗号分隔）。

```json
{
// ... 其他设置 ...

"http.proxy": "http://proxy.mycompany.com:8080", // 无认证

// 或者，如果需要认证:
// "http.proxy": "http://user123:passwordABC@proxy.mycompany.com:8080",

// 如果 HTTPS 需要独立配置 (通常不需要):
// "https.proxy": "http://secureproxy.mycompany.com:8888",

// 禁用严格 SSL 检查 (如果需要):
"http.proxyStrictSSL": false,

// 配置不走代理的地址:
"http.noProxy": [
    "localhost",
    "127.0.0.1",
    "*.myinternaldomain.com",
    "192.168.0.0/16"
]

// ... 其他设置 ...

}
```

关于 http.noProxy: 注意在 JSON 中，它是一个字符串数组 ([...])，而不是像设置界面那样用逗号分隔的单个字符串。每个不需要代理的地址是数组中的一个元素。

保存文件: 按 Ctrl + S (Windows/Linux) 或 Cmd + S (macOS) 保存 settings.json 文件。
重启 VS Code (推荐): 为了确保所有组件（包括扩展主机进程）都加载了新的代理设置，建议在修改 settings.json 后重启 VS Code。

安全提示 (再强调): 避免在 settings.json 中存储明文密码，尤其是当 .vscode 文件夹可能被提交到版本控制系统（如 Git）时。考虑使用环境变量（方法三）或更安全的凭据管理方式。

方法三：使用环境变量

VS Code 能够自动检测并使用操作系统级别的标准代理环境变量。这是一种更通用、有时也更安全（如果环境变量管理得当）的方式，特别是在需要为多个应用程序（包括命令行工具如 git, npm, curl 等）配置相同代理时。

标准的环境变量:

HTTP_PROXY: 用于 HTTP 请求的代理。
HTTPS_PROXY: 用于 HTTPS 请求的代理。
NO_PROXY: 指定不应通过代理访问的主机名或 IP 地址列表（通常是逗号分隔）。

设置环境变量的步骤 (因操作系统而异):

Windows:
1. 右键点击 "此电脑" (This PC) 或 "计算机" (Computer)，选择 "属性" (Properties)。
2. 点击 "高级系统设置" (Advanced system settings)。
3. 在 "高级" (Advanced) 选项卡下，点击 "环境变量" (Environment Variables)。
4. 在 "系统变量" (System variables) 或 "用户变量" (User variables for ) 区域，点击 "新建" (New)。
5. 变量名 (Variable name): 输入 HTTP_PROXY。
6. 变量值 (Variable value): 输入代理 URL，格式同上，例如 http://proxy.mycompany.com:8080 或 http://user:pass@proxy.server:port。
7. 重复步骤 5-6 设置 HTTPS_PROXY (通常可以设置为与 HTTP_PROXY 相同的值，除非有特殊要求)。
8. 重复步骤 5-6 设置 NO_PROXY，变量值为逗号分隔的列表，例如 localhost,127.0.0.1,*.mycompany.local。
9. 点击 "确定" 保存所有更改。
10. 重要: 您需要重新启动 VS Code (可能还需要注销并重新登录 Windows，或者重启计算机) 才能使新设置的环境变量生效。
macOS / Linux (Bash/Zsh Shell):
1. 打开您的终端 (Terminal)。
2. 编辑您的 shell 配置文件。根据您使用的 shell，可能是 ~/.bashrc、~/.bash_profile、~/.zshrc 或 ~/.profile。例如，使用 nano 编辑器：nano ~/.zshrc。
3. 在文件末尾添加以下行 (替换为您的实际代理信息):
  
```bash
export HTTP_PROXY="http://proxy.mycompany.com:8080"

如果需要认证:

export HTTP_PROXY="http://user123:passwordABC@proxy.mycompany.com:8080"

export HTTPS_PROXY="$HTTP_PROXY" # 通常 HTTPS 代理与 HTTP 相同

或者，如果不同:

export HTTPS_PROXY="http://secureproxy.mycompany.com:8888"

export NO_PROXY="localhost,127.0.0.1,*.mycompany.local,10.0.0.0/8"
`` * **注意:** 在 shell 脚本中设置包含特殊字符（如@,:,/`）的密码时要小心，可能需要进行 URL 编码或使用引号。
4. 保存文件 (在 nano 中是 Ctrl + X, 然后按 Y, 再按 Enter)。
5. 使更改生效。您可以运行 source ~/.zshrc (替换为您的配置文件名) 来立即加载新设置到当前终端会话，或者关闭并重新打开终端。
6. 启动 VS Code: 从已经加载了这些环境变量的终端启动 VS Code (在终端输入 code)，这样 VS Code 进程就能继承这些环境变量。如果您通过桌面图标启动 VS Code，它可能不会自动获取在 .bashrc / .zshrc 中设置的环境变量（这取决于您的桌面环境如何启动应用程序）。确保环境变量在系统级别或用户登录会话级别被设置可能更可靠。

环境变量的优势:

全局性: 一次设置，可能对系统上的多个应用生效。
安全性: 将凭据存储在环境变量中通常被认为比直接写入配置文件（尤其是可能被版本控制的文件）更安全一些，但仍需谨慎管理环境变量的访问权限。
优先级: VS Code 有一套代理设置的优先级规则。通常是：
1. VS Code settings.json 中的设置 (http.proxy, https.proxy) 优先级最高。
2. 如果 VS Code 设置未配置，则会查找并使用环境变量 (HTTP_PROXY, HTTPS_PROXY)。
3. 如果前两者都未配置，VS Code 在某些平台（如 Windows）上可能会尝试使用操作系统的系统级代理设置。

因此，如果您在 VS Code 的 settings.json 中明确配置了代理，它将覆盖环境变量的设置。 如果您想让 VS Code 使用环境变量，请确保 settings.json 中的 http.proxy 和 https.proxy 设置为空或被注释掉。

验证代理配置是否生效

配置完成后，您需要验证代理是否按预期工作。以下是一些验证方法：

扩展市场:
- 打开 VS Code 左侧活动栏的 "扩展" (Extensions) 视图 (图标像四个方块，一个分离)。
- 尝试搜索一个扩展，例如 "Python" 或 "Prettier"。
- 如果能够成功搜索并显示扩展列表、详情和安装按钮，说明 VS Code 至少能够通过代理访问扩展市场。尝试安装或更新一个扩展，观察是否成功。
VS Code 更新检查:
- 点击左下角的齿轮图标 -> "检查更新" (Check for Updates)。
- 如果 VS Code 能够成功连接到更新服务器并告知您是否有新版本，说明代理配置对更新功能有效。
Git 操作 (如果适用):
- 如果您使用 VS Code 的 Git 集成功能（例如克隆、拉取、推送远程仓库，特别是像 GitHub, GitLab 等外部仓库），尝试执行一个需要网络访问的操作。
- 打开源代码管理 (Source Control) 视图 (图标像一个分支)。
- 尝试 "克隆存储库" (Clone Repository) 一个公共仓库，或者在现有项目中执行 "拉取" (Pull) 或 "同步更改" (Sync Changes)。
- 注意: Git 本身也有自己的代理配置 (git config --global http.proxy ...)。VS Code 内置的 Git 功能通常会尝试使用 VS Code 的代理设置。但如果您在 VS Code 的集成终端 (Integrated Terminal) 中直接运行 git 命令，该终端是否使用 VS Code 的代理设置取决于 VS Code 的版本和设置（有些情况下终端会继承 VS Code 的代理环境变量）。如果终端中的 git 命令不工作，您可能还需要单独为 Git 配置代理，或者确保环境变量方法设置正确且终端已继承。
检查输出面板 (Output Panel):
- 按下 Ctrl + Shift + U (Windows/Linux) 或 Cmd + Shift + U (macOS) 打开输出面板。
- 在面板右上角的下拉菜单中，选择与网络相关的通道，例如 "Log (Window)"、"Git"、"Extension Host" 等。
- 进行网络操作（如安装扩展）时，观察这些通道中是否有关于代理连接成功或失败的日志信息。错误信息通常会提供线索。例如，查找包含 "proxy", "connect", "ECONNREFUSED", "SSL", "certificate" 等关键词的条目。
使用需要网络连接的扩展:
- 如果您安装了某些需要从互联网获取数据或服务的扩展（例如天气插件、代码片段同步工具、需要下载语言服务器或依赖的语言支持扩展），检查它们是否功能正常。

常见问题与故障排查 (Troubleshooting)

如果在配置或使用代理时遇到问题，可以尝试以下排查步骤：

检查代理信息准确性:
- 再次确认代理服务器地址、端口、用户名和密码是否完全正确，包括大小写（用户名/密码通常区分大小写）。
- 检查 URL 格式是否符合要求 (http://... 或 http://user:pass@...)。
防火墙问题:
- 确保您的本地防火墙（Windows Defender Firewall, macOS Firewall）或任何第三方安全软件没有阻止 VS Code (code.exe, Code Helper, etc.) 访问网络或连接到代理服务器。
- 确保公司/组织的防火墙允许从您的机器到代理服务器指定端口的连接。
代理服务器本身的问题:
- 确认代理服务器正在运行并且是可达的。可以尝试在命令行中使用 ping <代理服务器地址> 或 telnet <代理服务器地址> <端口号> (如果 telnet 可用) 来测试基本连接。
- 尝试在浏览器或其他支持代理的应用中配置相同的代理信息，看是否能正常工作。如果其他应用也无法通过代理，则问题可能出在代理服务器本身或您的网络环境。
认证失败:
- 如果代理需要认证，但您遇到 407 Proxy Authentication Required 错误，请仔细检查用户名和密码。
- 注意密码中可能包含特殊字符（如 @, #, !, % 等），这些字符在 URL 中可能需要进行 URL 编码 (Percent Encoding)。例如，p@ssword 应编码为 p%40ssword。您可以使用在线 URL 编码工具来转换密码。
- 示例 (编码后的密码): http://user123:p%40ssword@proxy.mycompany.com:8080
SSL/TLS 证书问题:
- 如前所述，如果遇到 SSL 错误（例如 UNABLE_TO_VERIFY_LEAF_SIGNATURE, CERT_SIGNATURE_FAILURE, SELF_SIGNED_CERT_IN_CHAIN），特别是在企业内部网络，很可能是因为代理服务器使用了自签名证书或进行了 SSL 拦截。
- 尝试将 http.proxyStrictSSL 设置为 false (在设置 UI 中取消勾选，或在 settings.json 中设为 false)。
- 再次强调: 禁用此选项会降低安全性，请务必了解风险。如果可能，更好的解决方案是让网络管理员将代理服务器的根证书添加到您操作系统的信任证书存储中。
http.noProxy 配置错误:
- 检查 http.noProxy 列表中的条目是否正确。确保使用了正确的域名、IP 地址或 CIDR 表示法。
- 注意通配符 * 仅在域名的开头有效（例如 *.example.com），不能用于 IP 地址。
- 在 settings.json 中，确保它是一个字符串数组，而不是逗号分隔的字符串。
检查 VS Code 设置优先级:
- 如果您同时使用了多种配置方法（例如 settings.json 和环境变量），请记住 settings.json 中的设置优先级更高。确保您期望生效的配置没有被更高优先级的设置覆盖。如果您想使用环境变量，请确保 settings.json 中的 http.proxy 和 https.proxy 已被移除或注释掉。
扩展可能不遵循 VS Code 代理设置:
- 虽然大多数设计良好的 VS Code 扩展会尊重 http.proxy 等设置，但并非所有扩展都保证如此。有些扩展可能使用自己的网络库或逻辑，可能需要单独配置代理，或者根本不支持代理。
- 如果某个特定扩展无法工作，请查阅该扩展的文档或 GitHub 仓库，看是否有关于代理配置的说明或已知问题。
查看开发者工具 (Developer Tools):
- 如果需要更深入地调试网络问题，可以打开 VS Code 的开发者工具。
- 打开命令面板 (Ctrl/Cmd + Shift + P)，输入 Developer: Toggle Developer Tools 并选择它。
- 切换到 "Console" 或 "Network" 选项卡，观察在进行网络操作时是否有更详细的错误信息或请求记录。
重启 VS Code: 有时候简单的重启就能解决问题，特别是更改了环境变量或系统级设置后。

安全性考量

密码安全: 避免在 settings.json 中存储明文密码，特别是当项目（包含 .vscode 文件夹）会被共享或提交到版本控制系统时。使用环境变量可能稍微安全一些，但最佳实践是使用不需要将凭据硬编码在易于访问的文件中的认证机制（如果代理支持，例如集成 Windows 认证 NTLM/Kerberos，但这通常需要 VS Code 或底层库的支持，目前 VS Code 对此支持有限，主要依赖用户名/密码形式）。如果必须使用密码，确保 settings.json 文件（尤其是工作区设置）受到适当保护。
禁用 proxyStrictSSL 的风险: 如前所述，禁用 SSL 验证会使您容易受到中间人攻击。只有在完全信任您的网络环境和代理服务器，并且确实无法通过添加信任证书解决问题时，才应考虑此选项。