2.6 🌐 网络环境配置

开发过程中，下载依赖、访问文档、调用 API 都需要网络。这节帮你配好网络环境，少踩坑。

🚨 为什么要单独讲网络？

在国内做开发，网络问题是最常见的「劝退原因之一」：

你：npm install
终端：⠋ ......
（等了 10 分钟）
终端：ETIMEDOUT
你：？？？？？

你：pip install requests
终端：ERROR: Could not find a version that satisfies the requirement
你：明明有网啊？？？

90% 的情况不是你的问题，是网络的问题。 配好镜像源/代理，问题就解决了。

🛤️ 两条路线

不管哪条路线，配好之后效果一样——能正常开发。

🇨🇳 国内路线：镜像源配置

原理是什么？

官方源（npmjs.org / pypi.org）在海外
├── 你在国内 → 跨太平洋去下载 → 慢/超时
│
镜像源（国内公司搭的同步服务器）
├── 你在国内 → 从国内服务器下载 → 快
├── 内容和官方完全一样，只是服务器在国内
└── 常用镜像：淘宝、腾讯、华为

npm 镜像源配置

# 查看当前源
npm config get registry

# 设置淘宝镜像源（推荐）
npm config set registry https://registry.npmmirror.com

# 验证
npm config get registry
# 期望输出：https://registry.npmmirror.com

# 测试下载速度
time npm install lodash
# 应该几秒就完成

pnpm 镜像源配置

# 设置淘宝镜像源
pnpm config set registry https://registry.npmmirror.com

# 验证
pnpm config get registry

yarn 镜像源配置

# 设置淘宝镜像源
yarn config set registry https://registry.npmmirror.com

# 验证
yarn config get registry

pip / PyPI 镜像源配置

# 临时使用（每次命令加参数）
pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple

# 永久配置（推荐）
# 🍎 Mac/Linux：
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

# 🪟 Windows（PowerShell）：
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

常用 PyPI 镜像源：

清华源：https://pypi.tuna.tsinghua.edu.cn/simple     ← 最推荐
阿里源：https://mirrors.aliyun.com/pypi/simple
豆瓣源：https://pypi.douban.com/simple
华为源：https://repo.huaweicloud.com/repository/pypi/simple

Homebrew 镜像（Mac 用户）

# 替换 Homebrew 默认源为清华源
export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"

# 写入 shell 配置文件（永久生效）
echo '# Homebrew 镜像源' >> ~/.zshrc
echo 'export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"' >> ~/.zshrc
echo 'export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"' >> ~/.zshrc
echo 'export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"' >> ~/.zshrc
echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"' >> ~/.zshrc
source ~/.zshrc

Git 镜像加速

# GitHub 访问慢？用 ghproxy 加速 clone
# 原始命令：
git clone https://github.com/user/repo.git

# 加速方式1：加代理前缀
git clone https://ghproxy.com/https://github.com/user/repo.git

# 加速方式2：用 Gitee 导入
# 1. 打开 gitee.com
# 2. 点「+」→「从 GitHub/GitLab 导入仓库」
# 3. 输入 GitHub 仓库地址
# 4. 从 Gitee clone（国内速度快）

一键配置脚本（国内用户）

把下面的脚本保存为 setup-cn.sh，一键配置所有国内源：

#!/bin/bash
echo "🇨🇳 正在配置国内镜像源..."

# npm
npm config set registry https://registry.npmmirror.com
echo "✅ npm 镜像源已配置"

# pnpm
pnpm config set registry https://registry.npmmirror.com 2>/dev/null
echo "✅ pnpm 镜像源已配置"

# pip
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple 2>/dev/null
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn 2>/dev/null
echo "✅ pip 镜像源已配置"

# 验证
echo ""
echo "=== 配置验证 ==="
echo "npm registry: $(npm config get registry)"
echo "pip index-url: $(pip config get global.index-url 2>/dev/null || echo '未安装 pip')"
echo ""
echo "🎉 全部配置完成！"

运行：

chmod +x setup-cn.sh
./setup-cn.sh

🌍 海外路线：代理配置

如果你已经有代理（VPN/代理工具），配置开发工具走代理。

代理是什么？

代理 = 网络请求的「中转站」

没有代理：
你的电脑 → 直接访问 Google → 被墙/很慢

有代理：
你的电脑 → 代理服务器（海外） → Google → 代理服务器 → 你的电脑

配置终端代理

# 假设你的代理工具运行在本地 7890 端口
# 常见代理端口：7890 (Clash)、1080 (SS)、10809 (V2Ray)

# 🍎 Mac/Linux（在终端里执行）：
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5://127.0.0.1:7890

# 🪟 Windows PowerShell：
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="socks5://127.0.0.1:7890"

# 验证代理是否工作
curl -I https://www.google.com
# 如果返回 200 OK 就说明代理正常

写入配置文件（永久生效）

# 🍎 Mac/Linux（写入 ~/.zshrc 或 ~/.bashrc）：
cat >> ~/.zshrc << 'EOF'

# 代理配置
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5://127.0.0.1:7890
EOF

source ~/.zshrc

Git 代理配置

# Git 单独配置代理
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

# 取消代理
git config --global --unset http.proxy
git config --global --unset https.proxy

npm 代理配置

# 设置代理
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890

# 取消代理（改回镜像源）
npm config delete proxy
npm config delete https-proxy

代理 vs 镜像源

代理（Proxy）：
├── 优点：所有流量都走代理，不限于特定工具
├── 缺点：需要代理工具，可能收费
└── 适合：已有代理工具的用户

镜像源（Mirror）：
├── 优点：免费，稳定，速度快
├── 缺点：只对特定工具生效，内容同步可能有延迟
└── 适合：没有代理工具的用户

建议：两者结合用
├── 日常开发：用镜像源（稳定）
├── 访问 GitHub/Google：用代理（灵活）

🔧 常见网络问题排查

问题 1：npm install 超时

# 症状
npm ERR! code ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org/xxx failed

# 排查步骤
# 1. 检查当前源
npm config get registry

# 2. 如果是官方源，切换到镜像源
npm config set registry https://registry.npmmirror.com

# 3. 清除缓存重试
npm cache clean --force
npm install

# 4. 还是不行？检查网络
ping registry.npmmirror.com

问题 2：pip install 报错

# 症状
ERROR: Could not find a version that satisfies the requirement xxx
# 或
HTTPSConnectionPool: Read timed out

# 排查步骤
# 1. 检查当前源
pip config get global.index-url

# 2. 设置清华源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

# 3. 重试
pip install xxx

# 4. 临时用指定源
pip install xxx -i https://pypi.tuna.tsinghua.edu.cn/simple

问题 3：git clone 很慢或失败

# 症状
fatal: unable to access 'https://github.com/xxx/xxx.git':
Failed to connect to github.com port 443: Timed out

# 解决方案1：用代理
git config --global http.proxy http://127.0.0.1:7890

# 解决方案2：用 ghproxy 加速
git clone https://ghproxy.com/https://github.com/xxx/xxx.git

# 解决方案3：用 Gitee 镜像
# 在 gitee.com 导入 GitHub 仓库，然后从 Gitee clone

# 解决方案4：用 SSH 代替 HTTPS
# 配置 SSH Key（一次性设置）
ssh-keygen -t ed25519 -C "your@email.com"
cat ~/.ssh/id_ed25519.pub
# 把公钥添加到 GitHub → Settings → SSH Keys
# 然后用 SSH 方式 clone
git clone git@github.com:xxx/xxx.git

问题 4：DNS 解析失败

# 症状
getaddrinfo ENOTFOUND registry.npmjs.org

# 排查步骤
# 1. 测试 DNS
nslookup registry.npmjs.org

# 2. 如果 DNS 有问题，换 DNS 服务器
# 🍎 Mac：
# 系统设置 → 网络 → DNS → 添加：
# 223.5.5.5（阿里 DNS）
# 8.8.8.8（Google DNS）

# 🪟 Windows：
# 设置 → 网络 → 更改适配器选项 → 属性 → IPv4 → DNS：
# 223.5.5.5
# 8.8.8.8

# 3. 或者在终端临时设置
# Mac/Linux：
echo "nameserver 223.5.5.5" | sudo tee /etc/resolv.conf

问题 5：GitHub 访问困难

# 症状：github.com 打不开、加载慢

# 方案1：修改 Hosts 文件
# 查询 GitHub 最新 IP：https://ipaddress.com/website/github.com
# 编辑 hosts 文件：
# 🍎 Mac/Linux：sudo vim /etc/hosts
# 🪟 Windows：C:\Windows\System32\drivers\etc\hosts

# 添加以下内容（IP 可能需要更新）：
140.82.114.4 github.com
199.232.69.194 github.global.ssl.fastly.net

# 刷新 DNS：
# Mac：sudo dscacheutil -flushcache
# Windows：ipconfig /flushdns

# 方案2：使用 GitHub 镜像站
# https://github.moeyy.xyz/https://github.com/xxx/xxx
# https://ghproxy.com/https://github.com/xxx/xxx

# 方案3：配代理（最稳定）

问题 6：SSL 证书错误

# 症状
SSL: CERTIFICATE_VERIFY_FAILED

# 解决方案（临时，不推荐长期使用）
# npm
npm config set strict-ssl false

# pip
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org xxx

# git
git config --global http.sslVerify false

# 推荐方案：更新证书
# Mac：运行 /Applications/Python\ 3.x/Install\ Certificates.command
# 或者：pip install --upgrade certifi

🧰 网络诊断工具箱

# 测试网络连通性
ping google.com
ping github.com

# 测试 DNS 解析
nslookup github.com
dig github.com

# 测试端口连通性
telnet github.com 443
# 或
nc -zv github.com 443

# 查看当前网络配置
# npm
npm config list
npm config get registry

# pip
pip config list

# git
git config --list | grep -i proxy

# 测试下载速度
time curl -o /dev/null https://registry.npmmirror.com/lodash

📋 配置检查清单

配置完后，过一遍这个清单：

# 运行这个脚本检查所有配置
echo "=== 网络环境检查 ==="
echo ""

echo "📦 npm registry:"
npm config get registry
echo ""

echo "📦 pnpm registry:"
pnpm config get registry 2>/dev/null || echo "pnpm 未安装"
echo ""

echo "🐍 pip index-url:"
pip config get global.index-url 2>/dev/null || echo "pip 未安装"
echo ""

echo "🔴 Git proxy:"
git config --global http.proxy 2>/dev/null || echo "未配置"
echo ""

echo "🌐 连通性测试..."
ping -c 1 registry.npmmirror.com > /dev/null 2>&1 && echo "✅ npm 镜像可达" || echo "❌ npm 镜像不可达"
ping -c 1 github.com > /dev/null 2>&1 && echo "✅ GitHub 可达" || echo "❌ GitHub 不可达"
echo ""
HEREDOC_END

🚨 为什么要单独讲网络？​

🛤️ 两条路线​

🇨🇳 国内路线：镜像源配置​

原理是什么？​

npm 镜像源配置​

pnpm 镜像源配置​

yarn 镜像源配置​

pip / PyPI 镜像源配置​

Homebrew 镜像（Mac 用户）​

Git 镜像加速​

一键配置脚本（国内用户）​

🌍 海外路线：代理配置​

代理是什么？​

配置终端代理​

写入配置文件（永久生效）​

Git 代理配置​

npm 代理配置​

代理 vs 镜像源​

🔧 常见网络问题排查​

问题 1：npm install 超时​

问题 2：pip install 报错​

问题 3：git clone 很慢或失败​

问题 4：DNS 解析失败​

问题 5：GitHub 访问困难​

问题 6：SSL 证书错误​

🧰 网络诊断工具箱​

📋 配置检查清单​

🚨 为什么要单独讲网络？

🛤️ 两条路线

🇨🇳 国内路线：镜像源配置

原理是什么？

npm 镜像源配置

pnpm 镜像源配置

yarn 镜像源配置

pip / PyPI 镜像源配置

Homebrew 镜像（Mac 用户）

Git 镜像加速

一键配置脚本（国内用户）

🌍 海外路线：代理配置

代理是什么？

配置终端代理

写入配置文件（永久生效）

Git 代理配置

npm 代理配置

代理 vs 镜像源

🔧 常见网络问题排查

问题 1：npm install 超时

问题 2：pip install 报错

问题 3：git clone 很慢或失败

问题 4：DNS 解析失败

问题 5：GitHub 访问困难

问题 6：SSL 证书错误

🧰 网络诊断工具箱

📋 配置检查清单