在包管理器中使用代理

要在 npm、pip、composer 等包管理器中使用代理，可以通过环境变量（HTTP_PROXY、HTTPS_PROXY）、命令行参数，或每个包管理器专有的配置文件来配置代理设置。

许多开发环境运行在企业防火墙之后，或需要对流量进行监控，因此出站连接必须使用 HTTP 或 HTTPS 代理服务器。包管理器需要从外部 registry 下载依赖，必须配置为通过此类代理转发网络请求才能正常工作。

代理配置的通用概念

代理服务器可以拦截并转发 HTTP 和 HTTPS 流量。访问这些代理通常需要身份验证。

代理 URL 格式

包含可选身份验证信息的标准代理 URL 格式为：

protocol://[user:password@]host:port

• protocol：http 或 https
• user:password：用于代理身份验证的可选凭据。
• host：代理服务器的主机名或 IP 地址。
• port：代理服务器监听的端口（例如 8080、3128）。

示例： http://user:[email protected]:8080

环境变量

在包括包管理器在内的各类工具中配置代理，最常用且几乎被普遍识别的方式是使用标准环境变量。

• HTTP_PROXY 或 http_proxy：指定 HTTP 请求使用的代理服务器。
• HTTPS_PROXY 或 https_proxy：指定 HTTPS 请求使用的代理服务器。
• NO_PROXY 或 no_proxy：以逗号分隔的主机名、域名或 IP 地址列表，这些目标将绕过代理。直接访问内部资源或本地开发服务器时，这一项至关重要。

在 Windows 上这些变量通常不区分大小写，而在类 Unix 系统上区分大小写。为获得最大兼容性，通常同时设置 UPPER_CASE 和 lower_case 两种写法。

# Example for Unix-like systems (Linux, macOS)
export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080" # 通常与 HTTP_PROXY 相同
export NO_PROXY="localhost,127.0.0.1,.internal.domain.com"

# For Windows Command Prompt
set HTTP_PROXY=http://user:[email protected]:8080
set HTTPS_PROXY=http://user:[email protected]:8080
set NO_PROXY=localhost,127.0.0.1,.internal.domain.com

# For Windows PowerShell
$env:HTTP_PROXY="http://user:[email protected]:8080"
$env:HTTPS_PROXY="http://user:[email protected]:8080"
$env:NO_PROXY="localhost,127.0.0.1,.internal.domain.com"

npm（Node Package Manager）

npm 可以通过其内置配置系统或环境变量进行配置。

通过 npm config 配置

npm 的首选方式是直接在其配置中设置代理，这样设置会被持久保存。

# Set HTTP proxy
npm config set proxy http://user:[email protected]:8080

# Set HTTPS proxy (often the same as HTTP proxy)
npm config set https-proxy http://user:[email protected]:8080

# To unset a proxy
npm config rm proxy
npm config rm https-proxy

# Verify settings
npm config get proxy
npm config get https-proxy

如果您的代理不需要身份验证，请省略 user:password@ 部分。

SSL 证书问题

在使用 HTTPS 代理，或通过 HTTP 代理访问 HTTPS registry 时，npm 可能遇到 SSL 证书验证问题。当代理拦截 HTTPS 流量并使用自己的、系统并不信任的证书重新加密时，就会出现这种情况。

解决方法：
1. 将代理的 CA 证书添加到系统信任库。 这是推荐的安全做法。
2. 让 npm 使用指定的 CA 证书文件：
bash npm config set cafile /path/to/proxy/ca-certificate.pem
3. 关闭严格 SSL 校验（不建议在生产环境使用）：
bash npm config set strict-ssl false
这会跳过证书校验，可能使您面临中间人攻击风险。仅在受控环境中作临时调试使用。

registry 配置

如果您的组织使用私有 npm registry（例如 Nexus、Artifactory），且它可直接访问或通过另一个代理访问，请确认 registry 设置正确。

npm config set registry https://my-private-registry.example.com/npm/

pip（Python Package Installer）

pip 支持通过命令行参数、环境变量或配置文件来配置代理。

命令行参数

对单条 pip 命令，使用 --proxy 参数：

pip install some-package --proxy http://user:[email protected]:8080

配置文件

若需持久化代理设置，请修改或创建 pip 配置文件。
* Linux/macOS：~/.config/pip/pip.conf 或 ~/.pip/pip.conf
* Windows：%APPDATA%\pip\pip.ini 或 %HOME%\pip\pip.ini

在 [global] 段中添加以下内容：

# ~/.config/pip/pip.conf or %APPDATA%\pip\pip.ini
[global]
proxy = http://user:[email protected]:8080

环境变量

pip 遵循标准的 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 环境变量。一旦设置，将被自动使用。

export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080"
export NO_PROXY="localhost,127.0.0.1,.internal.domain.com"
pip install some-package

SSL 证书问题

与 npm 类似，pip 也可能出现 SSL 错误。
1. 将代理的 CA 证书添加到系统信任库。
2. 为索引指定受信任的主机：
ini # ~/.config/pip/pip.conf or %APPDATA%\pip\pip.ini [global] trusted-host = pypi.org
这会让 pip 即使对该主机 SSL 校验失败也依然信任它。请谨慎使用。
3. 指定自定义 CA 证书包：
ini # ~/.config/pip/pip.conf or %APPDATA%\pip\pip.ini [global] cert = /path/to/proxy/ca-bundle.pem
或通过命令行：pip install some-package --cert /path/to/proxy/ca-bundle.pem

私有包索引

如果使用私有 Python 包索引（例如 Artifactory、Nexus），请配置 index-url 或 extra-index-url：

# ~/.config/pip/pip.conf or %APPDATA%\pip\pip.ini
[global]
index-url = https://my-private-pypi.example.com/simple/

Composer（PHP Dependency Manager）

Composer 的代理配置在很大程度上依赖环境变量，对于通过 Git 拉取的仓库，可能还需要配置 Git 的代理设置。

环境变量

Composer 主要使用标准的 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 环境变量。

export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080"
export NO_PROXY="localhost,127.0.0.1,.internal.domain.com"
composer install

Composer 配置（config.json）

虽然 Composer 的 config.json 中没有针对常规 HTTP/HTTPS 流量的直接 proxy 设置，但如果某些 VCS 仓库未被环境变量覆盖，或需要使用不同的代理，仍可为它们单独配置代理。

例如，为 Git 配置代理：

{
    "config": {
        "github-oauth": {
            "github.com": "YOUR_OAUTH_TOKEN"
        }
    }
}

这本身并不是代理设置，但说明了其他网络相关配置应放在哪里。真正的 Git 代理配置见下一节。

Git 代理配置

Composer 经常直接从 Git 仓库（例如 GitHub、GitLab）获取包。如果 Git 流量需要经过代理，您必须配置 Git 本身。

# Set HTTP proxy for Git
git config --global http.proxy http://user:[email protected]:8080

# Set HTTPS proxy for Git
git config --global https.proxy http://user:[email protected]:8080

# To unset
git config --global --unset http.proxy
git config --global --unset https.proxy

# Verify
git config --global --get http.proxy
git config --global --get https.proxy

如果您的 composer.json 使用 vcs 仓库或直接的 Git URL，这一点尤为重要。

SSL 证书问题

与其他工具一样，Composer 也可能遇到 SSL 问题。
1. 将代理的 CA 证书添加到系统信任库。
2. 配置 Git 关闭 SSL 校验（不推荐）：
bash git config --global http.sslVerify false
这应作为最后的手段，并且要格外谨慎。

常见代理问题排查

• 代理地址/端口错误：仔细核对主机名、IP 地址和端口。常见错误是对 HTTPS 代理使用了 HTTP，或反之。
• 身份验证失败：确认代理 URL 中的用户名和密码正确；若含特殊字符，需进行 URL 编码。
• SSL 证书错误：如果遇到 SSL_ERROR_SYSCALL、certificate verify failed 或类似错误，您的代理可能在进行 SSL 拦截。请将代理的根 CA 证书安装到系统信任库，或按上文所述让包管理器信任指定的 CA 证书包。
• NO_PROXY 问题：如果内部服务仍试图走代理，请检查 NO_PROXY 设置是否正确且完整。确保其中包含 localhost、127.0.0.1 以及所有相关的内部域名后缀。
• 防火墙拦截：确认本机防火墙或网络安全组允许出站连接到代理服务器的 IP 和端口。
• HTTP/HTTPS 混合配置：部分代理对 HTTP 和 HTTPS 的处理方式不同。如适用，请确保同时配置了 HTTP_PROXY 和 HTTPS_PROXY，或包管理器中对应的专有设置。

代理配置方式对比