# China Network Diagnostics

> Diagnose network access on macOS in mainland China: why a VPN client can be "running but not connected", the difference between system-proxy mode and TUN mode, why command-line tests disagree with the browser, how to verify the exit IP through the proxy port, and how to fetch GitHub / YouTube resources when direct connections fail.

- Skill: `wlkerwong-boop/china-network-diagnostics` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add wlkerwong-boop/china-network-diagnostics`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wlkerwong-boop/china-network-diagnostics/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: wlkerwong-boop (https://skillmd.com/u/wlkerwong-boop)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/wlkerwong-boop/china-network-diagnostics

---


# 国内网络连通性诊断（macOS）

> 适用：在中国大陆的 macOS 上判断"外网到底通不通"，以及在直连失败时拿到 GitHub / YouTube 的资源。
> 本文只讲**诊断方法与公开通道**，不含任何节点、订阅、服务商配置。

## 一、最容易误判的一件事：程序开着 ≠ 已连接

客户端有两种工作模式，**先分清模式，再下结论**：

| 模式 | 接管范围 | 命令行（curl/git）会走它吗 |
|---|---|---|
| **TUN / 全局接管** | 所有流量，进程级 | 会 |
| **系统代理模式** | 只改 macOS 系统代理设置 | **不会**（除非显式指定 `-x` 或 `http_proxy`） |

由此产生三个必然现象，全属正常：

1. 浏览器能打开外网，`curl https://www.google.com` 却超时；
2. `curl` 直连查出口 IP 显示国内 IP，但浏览器出口其实是国外的；
3. 系统代理模式下，桌面客户端显示"已连接"，而命令行测试显示"不通"——**两者并存不是故障**。

**铁律：禁止用命令行直连的结果断言"VPN 没连上"。** 必须走代理端口重测一遍再下结论。（曾因凭直连结果下结论而两次误报，向用户道歉纠正——这是本技能存在的原因。）

## 二、诊断序列（严格按顺序）

```bash
# 1. 系统代理是否启用、端口是多少
scutil --proxy | grep -E "HTTPEnable|HTTPPort|HTTPProxy|HTTPSEnable|HTTPSPort|SOCKSEnable|SOCKSPort"

# 2. 直连测试（预期可能不通，仅作对照）
curl -s -o /dev/null -w "直连: %{http_code} (%{time_total}s)\n" --max-time 6 https://www.google.com

# 3. 走代理端口实测（模拟浏览器视角）——这一步才是结论依据
curl -s -o /dev/null -w "走代理: %{http_code} (%{time_total}s)\n" --max-time 10 -x http://127.0.0.1:<HTTPPort> https://www.google.com

# 4. 走代理看出口 IP（显示国外 = 分流生效）
curl -s --max-time 10 -x http://127.0.0.1:<HTTPPort> https://myip.ipip.net

# 5. 进程活着不代表隧道建立：看有没有 ESTABLISHED 连接
lsof -nP -i -a -p <pid>
```

判定口径：
- 步骤 3 返回 `200` = 真的通；返回 `000`/超时 = 真的不通（此时才可以说"没连上"）。
- 直连不通 + 走代理通 = 系统代理模式在正常工作，浏览器可用。
- 走代理也 000 → 再看步骤 1 是否有端口、步骤 5 是否有 ESTABLISHED，才是"隧道没建立"。

一键探针：`scripts/vpn-probe.sh`（自动读系统代理端口，也支持手动传端口：`bash vpn-probe.sh 7890`）。

## 三、GitHub 下载（直连失败时）

症状：`git clone` 卡死 / 超时，而 `api.github.com` 偶尔还能通（不同域名不同待遇）。**不要反复重试同一条命令**（只会一直卡到超时）。

按优先级试：

1. **codeload（官方 zip 通道，通常最稳）**
   ```bash
   curl -L -o repo.zip https://codeload.github.com/<owner>/<repo>/zip/refs/heads/<branch>
   # 分支名不确定：curl -s https://api.github.com/repos/<owner>/<repo> | grep default_branch
   ```
2. **第三方镜像**（如 `https://gh-proxy.com/https://github.com/...`）——可用性会变，只当备选，自己核对。
3. **本机已有代理时给 git 单独指定**（`-c` 一次性，不污染全局配置）：
   ```bash
   git -c http.proxy=http://127.0.0.1:<HTTPPort> -c https.proxy=http://127.0.0.1:<HTTPPort> \
       clone --depth 1 <url>
   ```
   大仓库务必 `--depth 1`。

## 四、YouTube 字幕（yt-dlp）

```bash
yt-dlp --ignore-config --cookies-from-browser chrome \
  --proxy http://127.0.0.1:<HTTPPort> \
  --skip-download --write-subs --sub-langs "zh" --sub-format srt \
  --output "/tmp/video/video" "https://www.youtube.com/watch?v=XXX"
```

三个必知点：
- `--ignore-config`：`~/.config/yt-dlp/config` 里可能有旧版不认识的选项（如 `--js-runtimes node`），导致 "no such option" 直接退出；跳过配置即可。
- `--cookies-from-browser chrome`：YouTube 反爬会要求登录验证，直接复用浏览器已登录的 cookie。
- `--proxy`：系统代理模式下命令行工具**不会**自动走代理，必须显式指定。
- 先 `--list-subs` 确认该视频有哪些语言字幕，再下载。

## 五、给非技术用户的交付方式

- 结论先行 + 对比表（直连 vs 走代理）+ 大白话；
- 出错直接承认并给根因（例如"之前判断错了，因为我用命令行直连去测一个只对浏览器生效的代理"）；
- 用户看到的界面状态可能和实际不符（"程序开着"≠"已连接"），以实测为准，但**要用对测法**。

## 支持文件

- `scripts/vpn-probe.sh` — 一键探针：读系统代理 → 直连对照 → 走代理实测 → 出口 IP

