开发者用v2rayN配置终端代理：Git、npm与Docker工作流指南

开发者在 Windows 上使用 v2rayN 时，真正影响效率的往往不是浏览器能否打开网页，而是终端、Git、npm、Docker 以及各种 AI 编程工具是否都能正确使用代理。浏览器可以读取系统代理，并不代表命令行程序会自动读取；Docker CLI 的请求也不一定与宿主机上的 Git 使用同一套代理设置。结果就是网页访问正常，执行 git clone、npm install 或拉取容器镜像时却出现超时、TLS 握手失败和连接被重置。

本文以 v2rayN 7.x 和 Xray 内核为操作基线，整理一套从本地端口、终端环境变量到 Git、npm、Docker 和 TUN 模式的配置流程。示例使用 127.0.0.1:10808 作为 SOCKS 入口、127.0.0.1:10809 作为 HTTP 入口；如果你的 v2rayN 端口不同，应以“设置”→“参数设置”中的实际监听值和核心日志为准。

建立本地代理基线：先确认 v2rayN 真的能接收请求

终端代理的第一层不是 Git 或 npm，而是 v2rayN 在本机提供的入站端口。客户端界面显示“运行中”只说明核心进程已经启动，不能证明端口仍然监听，也不能证明当前节点能完成远端握手。建议先选择一个确认可用的节点，启用 v2rayN 的系统代理，再用 PowerShell 检查端口。

• 打开 v2rayN，确认当前节点已经选中，并在“设置”→“参数设置”→“核心设置”中确认正在使用的核心与节点协议相容。
• 检查“设置”→“参数设置”中的本地 SOCKS、HTTP 或混合端口。不要同时启动两个会占用相同端口的核心。
• 在 PowerShell 中执行端口测试，确认本地进程正在监听：

Test-NetConnection 127.0.0.1 -Port 10808
Test-NetConnection 127.0.0.1 -Port 10809

如果结果中的 TcpTestSucceeded 为 True，只能说明本地入口存在；随后还要通过代理访问一个 HTTPS 地址，验证节点和代理协议。PowerShell 自带的 Invoke-WebRequest 对 SOCKS 的支持并不适合作为统一测试，因此可以先使用 v2rayN 的系统代理测试浏览器，再在终端中配置 HTTP 代理完成第二次验证。

配置终端环境变量：让命令行工具获得统一入口

许多开发工具会读取 HTTP_PROXY、HTTPS_PROXY 和 ALL_PROXY 环境变量，但读取规则并不完全一致。HTTP 代理通常写成 http://127.0.0.1:10809，SOCKS5 代理则写成 socks5://127.0.0.1:10808。不要把 SOCKS 端口和 HTTP 端口混用，也不要给已经是 HTTPS 的目标强行填写 https://127.0.0.1:10809；这里的协议表示“连接代理服务器的方式”，不是目标网址的协议。

1. 打开终端

   在 Windows Terminal 中新建 PowerShell 标签页，先执行 Get-ChildItem Env:*PROXY*，查看是否残留旧代理变量。

2. 设置当前会话

   执行 $env:HTTP_PROXY="http://127.0.0.1:10809"、$env:HTTPS_PROXY="http://127.0.0.1:10809" 和 $env:ALL_PROXY="socks5://127.0.0.1:10808"，只影响当前终端窗口。

3. 补充绕过列表

   设置 $env:NO_PROXY="localhost,127.0.0.1,::1,.local"，让本机服务、回环地址和常见局域网名称不经过远端节点。

4. 验证变量生效

   关闭并重新打开目标工具，检查其诊断输出或执行一次依赖请求；新启动的进程才会继承当前会话中的变量。

$env:HTTP_PROXY="http://127.0.0.1:10809"
$env:HTTPS_PROXY="http://127.0.0.1:10809"
$env:ALL_PROXY="socks5://127.0.0.1:10808"
$env:NO_PROXY="localhost,127.0.0.1,::1,.local"

如果希望新开的 PowerShell 都使用同一配置，可以通过“设置”→“系统”→“系统信息”→“高级系统设置”→“环境变量”添加用户变量。不过全局持久化代理会影响公司内网、局域网开发服务和无需代理的镜像源，建议先使用当前会话验证，确认工作流稳定后再决定是否持久化。临时取消变量时执行 Remove-Item Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:ALL_PROXY，并重新启动工具。

Git 与 npm：分别保存配置，避免相互覆盖

Git 的 HTTP 与 SOCKS 配置

Git 访问远程仓库时通常通过 HTTP 或 HTTPS 建立连接。最容易兼容的方式是使用 v2rayN 的 HTTP 入口，并把代理写入 Git 的全局配置。这样配置只作用于 Git，不会改变浏览器或其他程序。

git config --global http.proxy http://127.0.0.1:10809
git config --global https.proxy http://127.0.0.1:10809
git config --global --get-regexp "http\..*proxy"

如果当前 v2rayN 只开放 SOCKS5，可以尝试：

git config --global http.proxy socks5h://127.0.0.1:10808
git config --global https.proxy socks5h://127.0.0.1:10808

socks5h 会让域名解析也交给代理端完成，适合本地 DNS 无法解析目标域名的环境。使用 HTTP 代理时，Git 的 HTTPS 请求仍然是通过 HTTP CONNECT 建立隧道，代理地址写成 http:// 是正常的。企业内网或代码托管服务不需要代理时，可使用 NO_PROXY 环境变量，或为特定域名单独取消代理配置。

git config --global --unset http.proxy
git config --global --unset https.proxy
git config --global --get-regexp "proxy"

执行 git clone 仍然超时时，应先检查远端地址、节点连接和系统时间，再看 Git 的详细输出。不要用反复重试掩盖认证问题；代理只能解决网络路径问题，不能修复无权限、凭据过期或远端仓库不存在。

npm 的代理、证书与依赖源

npm 通常读取自身配置中的 proxy 和 https-proxy，也可能读取环境变量。推荐为 npm 单独设置与 Git 相同的 HTTP 入口：

npm config set proxy http://127.0.0.1:10809
npm config set https-proxy http://127.0.0.1:10809
npm config get proxy
npm config get https-proxy

如果项目使用内部 npm registry，应先确认 registry 地址和访问权限。公网依赖请求失败时，不要直接把 strict-ssl 永久改为 false；这会降低 HTTPS 证书校验能力，而且无法解决节点不可达。只有在企业网络明确部署了自定义证书，并且已经按管理员要求导入 CA 的情况下，才应调整证书信任链。

npm config get registry
npm config delete proxy
npm config delete https-proxy

部分包管理工具会读取项目目录下的 .npmrc，因此还要检查项目配置是否覆盖了用户级设置。多人协作项目不建议把带有个人代理地址、账号或令牌的配置提交到代码仓库。更稳妥的做法是把本机代理写入用户配置，把 registry、缓存目录等团队设置放入不含敏感信息的项目配置。

Docker 工作流：区分 CLI、Engine 与构建阶段

Docker 是开发者代理配置中最容易误判的一环。宿主机上的 docker pull 由 Docker CLI 向 Docker Engine 发出请求，但真正访问镜像仓库的是 Engine。即使 PowerShell 中已经设置了代理变量，Docker Engine 也可能完全不知道这些变量。因此 Docker 需要单独配置，且要区分拉取镜像、构建镜像时下载依赖，以及容器运行时访问网络。

• Docker CLI：负责接收命令并与 Engine 通信，部分命令会读取客户端配置文件。
• Docker Engine：负责访问镜像仓库、拉取镜像层和执行构建，桌面环境下通常由 Docker Desktop 管理。
• 构建阶段：执行 Dockerfile 中的 RUN npm install、apt-get 或其他下载命令，需要通过构建参数或镜像内环境变量传递代理。
• 容器运行阶段：应用启动后的请求是否走代理，取决于容器内的环境变量、应用自身设置和 Docker 网络路径。

使用 Docker Desktop 时，在其设置页面找到网络或代理相关选项，填写 v2rayN 的 HTTP 代理地址，例如 http://host.docker.internal:10809 或按 Docker Desktop 当前网络说明填写。宿主机上的 127.0.0.1 对容器并不总是等于宿主机，因此不能机械地把容器内的代理地址写成 127.0.0.1:10809。修改后重启 Docker Desktop，再执行：

docker version
docker pull hello-world
docker info

如果只希望构建阶段使用代理，可以在构建时传入参数：

docker build \
  --build-arg HTTP_PROXY=http://host.docker.internal:10809 \
  --build-arg HTTPS_PROXY=http://host.docker.internal:10809 \
  --build-arg NO_PROXY=localhost,127.0.0.1,.local \
  -t demo-app:local .

对应的 Dockerfile 可以声明代理参数，但不要把代理地址、认证信息或访问令牌写入镜像层。构建完成后检查最终镜像环境，确保没有把本机代理配置意外带入生产镜像。对于容器运行时，可以在编排文件中通过环境变量注入；生产环境应使用专门的网络策略，而不是依赖开发机上的 v2rayN 地址。

TUN 模式与应用分流：处理不读取代理变量的工具

有些 AI 编程工具、IDE 内置组件、语言服务器和独立更新器不会读取系统代理、Git 配置或 npm 配置。此时继续增加环境变量并不会改变它们的网络路径。v2rayN 的 TUN 模式通过虚拟网卡接收更广泛的 IP 流量，适合处理这类不支持显式代理的应用，但它会扩大接管范围，也更需要注意 DNS、路由顺序和局域网访问。

1. 先验证普通代理

   在 v2rayN 中选定节点，启用系统代理，确认浏览器和 Git 至少有一项能够正常访问，再开始 TUN 排查。

2. 打开 TUN 设置

   进入 v2rayN 的“设置”→“参数设置”→“Tun 模式”或相近菜单，启用虚拟网卡；Windows 可能需要管理员权限。

3. 保留本地直连

   将 127.0.0.0/8、10.0.0.0/8、172.16.0.0/12、192.168.0.0/16 等本地网段放入直连或绕过规则。

4. 验证开发服务

   依次测试本地 API、内网 Git、外部依赖源和镜像拉取；不要一开始就把所有流量设为代理。

TUN 模式开启后，如果本地开发服务器无法访问，优先检查路由中是否误把回环地址和局域网地址送入代理。若域名分流结果不符合预期，检查 DNS 模式与 domainStrategy；域名过早解析为 IP 后，原本针对域名的规则可能无法命中。使用 TUN 时还要留意其他 VPN、虚拟网卡、容器网络和安全软件之间的冲突，多个程序同时修改默认路由时，表现可能是连接时好时坏。

故障定位与日常维护：用单变量方式保持稳定

开发工作流中最危险的做法是同时切换节点、核心、TUN、DNS 和 npm registry，然后根据一次成功或失败下结论。更可靠的方法是固定一个已知可用节点，先关闭 TUN，只使用 HTTP 代理验证 Git；再验证 npm；最后单独配置 Docker。每一步只修改一个设置，并记录端口、节点名称、时间和报错原文。

日常使用时，可以把“开始开发”固定为一套检查：启动 v2rayN，确认节点和核心状态；查看系统代理端口；打开新的终端并确认代理变量；执行一次轻量 Git 或 npm 请求；需要容器时再检查 Docker Engine 状态。结束工作后，如果不希望其他程序继续使用代理，应关闭系统代理或清除持久化环境变量。代理配置中不要保存账号、令牌和私人订阅地址，也不要把带有个人网络信息的配置提交到项目仓库。