跳到内容在受限网络中如何为 GitHub Codespaces 使用代理
GitHub Codespace 会在托管环境中运行开发容器，而显示该环境的浏览器则运行在你自己的设备上。区分这一点很重要：在容器中配置代理，可以让 Codespace 通过代理下载软件包，但不会自动改变本地浏览器访问网站的方式。了解 GitHub Codespaces 如何配置代理时，也要先分清容器流量和本地浏览器流量。
如果依赖项安装在公司防火墙后失败，先确认是哪条连接被拦截。找到原因后，才能确定应该在哪里配置代理，以及需要让组织开放哪些访问权限。
1. 确认 Codespaces 的哪些流量需要使用代理
先列出具体失败的操作。通过 pip 安装 Python 软件包、用 npm 获取 Node.js 依赖，或在终端中下载命令行工具，都是由开发容器中的软件发起的请求。相比之下，在笔记本电脑上打开的浏览器标签页走的是笔记本电脑的网络路径。
弄清这一区别可以省下不少时间。如果本地浏览器无法加载某个网站，在 Codespace 中添加 HTTPS_PROXY 可能毫无作用。如果 npm install 在 Codespace 终端中失败，只在笔记本电脑上配置代理也可能无济于事。
记下出错的工具、它尝试访问的目标，以及请求是由终端、编辑器扩展还是本地浏览器发出的。例如，pip install 出错说明问题出在容器流量上；本地浏览器中的登录页面无法打开，则可能是本地网络或浏览器配置的问题。
尽量缩小代理的适用范围。如果只有一个软件包仓库被拦截，却让所有流量都经过代理，可能会引发不必要的问题，尤其是在内部服务本应直接访问的情况下。
2. 确认组织的代理允许哪些访问
向网络管理员询问代理主机名和端口、所需协议以及身份验证方式。还要确认代理是否需要用户名和密码、客户端证书，或安装在容器中的证书颁发机构证书。不要根据其他设备上的代理设置自行猜测这些信息。
针对具体任务，询问允许访问的目标地址。软件包管理器可能需要访问软件包仓库，而工具安装程序则可能从另一个发布站点下载文件。管理员可以确认允许访问的主机名；开始排查前先记下这些信息，才能区分是目标地址被拦截，还是代理地址配置错误。
确认是否启用了 HTTPS 检查。如果启用，代理可能会提供由组织签发的证书，而不是工具预期的公共证书颁发机构证书。组织的证书和获准的安装流程应由管理员提供，不要从错误消息中复制证书来使用。
如果你正在比较代理类型，或为其他工具配置访问权限，可以参考代理身份验证最佳实践指南，了解如何安全地处理凭据。如需更全面地考虑网络路由方案，请参阅如何选择 VPN；VPN 和代理在 Codespaces 中的配置方式并不相同。
3. 为开发容器配置代理变量
许多命令行工具会读取环境变量 HTTP_PROXY 和 HTTPS_PROXY。Codespaces HTTPS_PROXY 设置方法是：在开发容器环境中设置这些变量，并使用管理员提供的地址格式。常见格式类似 http://proxy.example.net:8080，但应使用组织实际指定的协议、主机名和端口。
对应该绕过代理的目标地址（例如获准访问的内部服务或本地地址），设置 NO_PROXY。具体条目取决于你的网络和工具。范围过宽可能会让内部请求走到非预期的网络路径；范围过窄则可能导致请求仍直接访问被拦截的目标。
要快速进行临时测试，可以在运行命令前于终端会话中设置变量。这有助于确认软件包能否安装，但并不能可靠地配置所有终端或之后启动的 Codespace。不同 Shell 的语法也不尽相同；避免将包含凭据的代理 URL 粘贴到可能会保存命令历史的命令行中。
如果希望项目设置能够重复使用，可将非敏感设置写入仓库使用的开发容器配置中，例如适当的 Dev Container 配置或设置脚本。不要把密码和令牌写入受版本控制的文件。如果需要凭据，请使用组织认可的密钥注入方式，并确认哪些进程可以读取这些凭据。
不要假设所有应用都会使用这些变量。有些工具读取小写形式的变量，有些使用自己的配置文件，还有些会忽略环境变量。请直接测试出错的命令；仅仅看到 HTTPS_PROXY 已设置，并不能证明 Codespace 的所有流量都经过了代理。
4. 让代理设置在重建 Codespace 后仍然有效
在某个终端中输入的设置可能会在关闭终端或重建 Codespace 后消失。若要持续使用项目所需的非敏感设置，请将其写入开发容器创建时会应用的仓库级配置。这样，团队成员打开同一项目时也能获得相同的基础设置，而不必把个人凭据复制到仓库中。
如果代理只适用于你的账户，或设置值属于敏感信息，个人设置可能更合适。选择这种方式前，请先检查组织的 Codespaces 策略和可用设置：管理员可能会限制个人配置、密钥或特定开发容器功能的使用。
更改配置后，如果改动会影响容器的创建方式，就重建 Codespace；随后打开一个新的终端并检查变量。重建是一个很好的验证方式：如果代理设置在重建后消失，很可能它只写入了之前的 Shell，而没有保存到持久化配置中。
将共享配置与密钥分开管理。仓库可以说明代理变量的名称和预期格式，但实际密码应通过获准的密钥机制提供。这样可以避免在日常提交中泄露凭据，让所有能查看项目历史记录的人都看到。
5. 按需信任代理证书
如果 HTTPS 请求因证书验证错误而失败，并且组织确认启用了 HTTPS 检查，容器可能需要信任组织的证书颁发机构。请向管理员获取官方证书和安装说明。不要通过禁用证书检查来绕过问题；这可能会掩盖拦截问题，而不是解决它。
安装流程取决于容器的操作系统和基础镜像。基于 Debian 或 Alpine 的镜像，以及特定语言的镜像，处理证书包的方式可能各不相同。还要确认是否必须在创建容器时添加证书，才能让它在重建后继续生效。
安装完成后，使用最初出错的同一工具，向获准访问的目标发起一次普通 HTTPS 请求。如果浏览器可以正常访问，但命令行客户端仍报告颁发者不受信任，该客户端可能使用独立的证书存储，或需要单独设置。在更改信任配置前，先向管理员确认容器应使用的证书文件及格式。
6. 分别测试 Git 和开发工具
先向管理员批准访问的目标发起一个无害请求，然后测试出错的软件包管理器或工具。某个命令请求成功，并不代表 Git、pip、npm 和特定语言的安装程序都会以相同方式使用代理。
对于 Git，请确认当前安装版本在你的配置中是否会读取代理环境变量。如果不会，Git 可能需要单独配置代理。避免将密码直接写入可能被提交或复制到日志中的 Git 配置文件；请改用组织认可的凭据管理方式。
对于软件包管理器，既要检查代理设置，也要检查已配置的软件包仓库。指向内部仓库的软件包管理器可能不需要访问与直接下载相同的外部目标；而下载发布归档文件的工具则可能会联系另一个主机。请将错误信息中的目标地址与收到的允许名单进行对照。
记录哪些测试成功或失败，以及涉及的主机名。这样，管理员就能根据具体信息采取行动，例如：“Git 可以访问获准的主机，但软件包仓库返回代理拒绝访问”，而不是只收到一句含糊的“Codespaces 无法上网”。
7. 排查连接失败，同时避免泄露凭据
GitHub Codespaces 代理连接失败怎么排查？先使用获准访问的目标进行无害的连通性测试，并检查结果是否指向 DNS 解析失败、连接超时、代理身份验证失败、目标地址被拒绝或证书验证失败。不同问题对应不同的处理步骤。例如，连接超时与身份验证被拒绝并不是一回事。
确认代理主机名和端口与管理员提供的信息一致，并确保运行测试的终端会话中确实存在相应变量。如果代理需要身份验证，凭据缺失或已过期时，即使地址正确也可能无法访问。
分享终端输出前，请删除用户名、密码、令牌和包含凭据的 URL。代理错误可能包含完整的请求地址，而 Shell 历史也可能保留含有密钥的命令。分享错误类型、目标主机名、工具名称和发生时间即可；这些信息通常足以让网络支持团队查询日志。
如果代理在一个 Codespace 中正常工作，但在另一个中不行，请比较它们的容器配置、操作系统镜像、环境变量和证书设置。每次只做一项更改，然后重复相同的测试。这样更容易判断问题是变量缺失、目标地址被拦截，还是证书信任存储不同所致。