# WSL2 开发环境一键配置脚本

将 WSL2 Ubuntu 打造为功能完备的开发工作中心。单文件模块化 Shell 脚本，支持 Ubuntu 20.04/22.04/24.04/26.04，幂等可重复执行。

## User Review Required

> [!IMPORTANT]
> **脚本文件位置**: 计划放置于 `rmdc-continuous-integration/scripts/wsl/wsl-dev-setup.sh`，如有其他偏好请指出。

> [!IMPORTANT]
> **终端方案选择**: 采用 **Zinit + Starship** 组合替代 oh-my-zsh：
> - **Zinit**：现代 Zsh 插件管理器，支持 Turbo 模式延迟加载，启动速度远超 oh-my-zsh
> - **Starship**：Rust 编写的跨 Shell 提示符，极快且美观，原生支持 Nerd Font 图标
> - 如更偏好 **Powerlevel10k**（纯 Zsh、瞬时启动），请告知

> [!IMPORTANT]
> **Node.js 管理器**: 采用 **fnm** (Fast Node Manager，Rust 编写) 替代 nvm，速度快 40x。如偏好 nvm 请告知。

## Open Questions

> [!NOTE]
> **代理模式**：Clash Verge TUN 模式下，WSL2 流量通常已自动代理。脚本默认 **不设置** 显式 `HTTP_PROXY` 环境变量，但提供 `--proxy` 开关可手动启用（用于 TUN 未覆盖 WSL 的场景）。是否需要默认启用？

## Proposed Changes

### 脚本架构

单文件 `wsl-dev-setup.sh`，约 1000+ 行，函数式模块化设计：

```
wsl-dev-setup.sh
├─ 📋 全局配置区（环境变量、默认值）
├─ 🎨 日志与颜色（log_info/warn/error/success，进度条）
├─ 🔧 工具函数（run_as_user, backup_file, download_file, add_to_rc）
├─ 🖥️ 系统检测（Ubuntu 版本、架构、WSL 检测）
├─ 🌐 代理配置（Clash Verge 可选显式代理）
├─ 📦 APT 镜像源（清华/中科大/阿里云，自动适配 DEB822 格式）
├─ 🌍 Locale 配置（en_US.UTF-8 + zh_CN.UTF-8）
├─ 🛠️ 基础工具安装（curl/git/wget/telnet/ping/mtr 等）
├─ 💻 Zsh + Zinit + Starship（终端环境）
├─ 🔤 Nerd Font 安装（JetBrains Mono Nerd Font）
├─ ⚡ 现代 CLI 工具（bat/eza/fd/ripgrep/fzf/zoxide/delta/lazygit）
├─ 🐹 Go 最新版安装（自动检测最新版本 + goproxy.cn）
├─ 📗 Node.js LTS 安装（fnm + npmmirror.com）
├─ 📊 安装总结与验证
└─ 🚀 Main（参数解析、模块调度）
```

---

### [NEW] [wsl-dev-setup.sh](file:///c:/Users/wdd/Documents/IdeaProjects/RMDC-CLOUD/rmdc-continuous-integration/scripts/wsl/wsl-dev-setup.sh)

#### 1. 命令行接口

```bash
# 完整安装（推荐）
sudo bash wsl-dev-setup.sh

# 查看帮助
bash wsl-dev-setup.sh --help

# 仅安装指定模块
sudo bash wsl-dev-setup.sh --only golang,nodejs

# 跳过指定模块
sudo bash wsl-dev-setup.sh --skip fonts,modern-cli

# 启用显式代理（TUN 未覆盖 WSL 时）
sudo bash wsl-dev-setup.sh --proxy

# 自定义配置
sudo WINDOWS_HOST_IP=192.168.1.100 CLASH_PROXY_PORT=7891 bash wsl-dev-setup.sh
```

可选模块名：`proxy | mirror | locale | base-tools | zsh | fonts | modern-cli | golang | nodejs`

#### 2. 系统检测与版本适配

| Ubuntu 版本 | APT 格式 | 特殊处理 |
|------------|----------|---------|
| 20.04 Focal | `sources.list` 传统格式 | 部分工具需从 GitHub Release 安装（eza/bat 等 apt 版本过旧） |
| 22.04 Jammy | `sources.list` 传统格式 | 大部分工具可直接 apt 安装 |
| 24.04 Noble | DEB822 `.sources` 格式 | 原生支持新格式，apt 源更丰富 |
| 26.04 | DEB822 `.sources` 格式 | 动态检测 codename，前向兼容 |

版本检测逻辑：
- 读取 `/etc/os-release` 获取 `VERSION_ID` 和 `VERSION_CODENAME`
- 校验是否为 WSL 环境（`/proc/version` 包含 `microsoft`）
- 检测架构（amd64/arm64）

#### 3. APT 镜像源配置

支持三大镜像源（默认清华 TUNA）：

| 镜像源 | URL |
|--------|-----|
| 清华 TUNA | `mirrors.tuna.tsinghua.edu.cn` |
| 中科大 USTC | `mirrors.ustc.edu.cn` |
| 阿里云 | `mirrors.aliyun.com` |

- **Ubuntu < 24.04**：修改 `/etc/apt/sources.list`，备份原文件
- **Ubuntu >= 24.04**：修改 `/etc/apt/sources.list.d/ubuntu.sources`（DEB822 格式）
- 自动启用 `main restricted universe multiverse` 四个仓库

#### 4. 基础工具安装

```
核心网络工具：curl wget git net-tools inetutils-telnet iputils-ping mtr-tiny dnsutils traceroute
编译工具链：  build-essential gcc g++ make cmake
系统工具：    ca-certificates gnupg lsb-release software-properties-common
压缩工具：    unzip zip tar gzip bzip2 xz-utils p7zip-full
实用工具：    jq tree htop ncdu openssh-client tmux
```

#### 5. Zsh + Zinit + Starship 终端

**Zinit 插件列表**：

| 插件 | 功能 | 加载方式 |
|------|------|---------|
| `zsh-autosuggestions` | Fish 风格命令建议 | Turbo 延迟加载 |
| `zsh-syntax-highlighting` | 命令语法高亮 | Turbo 延迟加载 |
| `zsh-completions` | 额外补全规则 | Turbo 延迟加载 |
| `fzf-tab` | fzf 驱动的 Tab 补全 | Turbo 延迟加载 |
| `history-substring-search` | 历史子串搜索 | Turbo 延迟加载 |
| OMZ::lib/history.zsh | oh-my-zsh 历史配置 | Snippet |
| OMZ::lib/key-bindings.zsh | oh-my-zsh 快捷键 | Snippet |
| OMZ::lib/completion.zsh | oh-my-zsh 补全配置 | Snippet |
| OMZ::plugins/git | Git 快捷别名 | Snippet |
| OMZ::plugins/sudo | 双击 ESC 添加 sudo | Snippet |
| OMZ::plugins/extract | 万能解压命令 | Snippet |
| OMZ::plugins/z | 智能目录跳转 | Snippet |

**Starship 配置**：
- 预设美观主题（Nerd Font 图标丰富）
- 显示：Git 分支/状态、Go 版本、Node.js 版本、执行时间、错误码
- 自定义 `~/.config/starship.toml`

**Zsh 增强配置**：
- 历史记录：50000 条，去重、共享
- 补全：菜单选择、大小写不敏感、模糊匹配
- 常用别名：`ll`, `la`, `..`, `...`, `cls`, `ports` 等

#### 6. Nerd Font 安装

- 下载 **JetBrains Mono Nerd Font**（从 GitHub Release）
- 安装到 `~/.local/share/fonts/`（Linux 侧）
- 同时复制到 `/mnt/c/Users/<user>/AppData/Local/Microsoft/Windows/Fonts/`（Windows 侧，供 Windows Terminal 使用）
- 运行 `fc-cache -fv` 刷新字体缓存
- 输出 Windows Terminal 字体配置提示

#### 7. 现代 CLI 工具

| 工具 | 替代 | 安装方式 |
|------|------|---------|
| `bat` | cat | apt (22.04+) / GitHub Release (20.04) |
| `eza` | ls | apt (24.04+) / GitHub Release (旧版) |
| `fd-find` | find | apt |
| `ripgrep` | grep | apt |
| `fzf` | — | apt / GitHub Release |
| `zoxide` | cd/z | apt (24.04+) / GitHub Release |
| `delta` | diff | GitHub Release |
| `lazygit` | git TUI | GitHub Release |
| `tldr` | man | npm (Node.js 安装后) |

#### 8. Go 最新版安装

- 自动从 `https://go.dev/dl/?mode=json` 检测最新稳定版
- 下载 `go<version>.linux-<arch>.tar.gz` 并安装到 `/usr/local/go`
- 创建 `$HOME/go/{bin,src,pkg}` 目录

**环境变量配置**（写入以下所有位置）：

| 文件 | 说明 |
|------|------|
| `/etc/profile.d/golang.sh` | 系统级，所有用户生效 |
| `~/.bashrc` | Bash 交互式 Shell |
| `~/.zshrc` | Zsh 交互式 Shell |
| `~/.profile` | 登录 Shell（sh/bash） |

```bash
export GOROOT=/usr/local/go
export GOPATH=$HOME/go
export PATH=$GOROOT/bin:$GOPATH/bin:$PATH
export GOPROXY=https://goproxy.cn,direct
export GONOSUMDB=*
```

#### 9. Node.js LTS 安装

- 安装 **fnm**（Fast Node Manager）从 GitHub Release
- 安装 Node.js 最新 LTS 版本
- 设置 npm 中国镜像：`registry.npmmirror.com`

**环境变量配置**（写入以下所有位置）：

| 文件 | 说明 |
|------|------|
| `~/.bashrc` | `eval "$(fnm env --shell bash)"` |
| `~/.zshrc` | `eval "$(fnm env --shell zsh)"` |
| `~/.profile` | `eval "$(fnm env)"` |

#### 10. 代理配置（可选）

当 `--proxy` 启用时：

```bash
export http_proxy="http://192.168.1.20:7890"
export https_proxy="http://192.168.1.20:7890"
export no_proxy="localhost,127.0.0.1,::1,192.168.0.0/16,10.0.0.0/8"
```

- 写入 `~/.bashrc`、`~/.zshrc`、`~/.profile`
- 配置 `git config --global http.proxy` 和 `https.proxy`
- 提供 `proxy_on` / `proxy_off` 快捷函数

---

## 设计决策

| 决策点 | 选择 | 理由 |
|--------|------|------|
| 插件管理器 | Zinit | Turbo 延迟加载，启动 < 100ms，远快于 oh-my-zsh（通常 500ms+） |
| 提示符 | Starship | Rust 编写极快，跨 Shell（bash/zsh 都能用），丰富图标 |
| Node.js 管理 | fnm | Rust 编写，比 nvm 快 40x，支持 `.node-version` / `.nvmrc` |
| 字体 | JetBrains Mono Nerd | 编程利器，包含 6000+ 图标，Ligature 支持 |
| 镜像源 | 清华 TUNA（默认） | 国内速度最快最稳定的开源镜像之一 |
| APT 格式 | 自动适配 | 24.04+ 用 DEB822，旧版用 sources.list |
| Go 代理 | goproxy.cn | 国内最快的 Go 模块代理 |
| npm 镜像 | npmmirror.com | 淘宝 npm 镜像，国内标配 |

## Verification Plan

### 脚本内置验证

脚本执行完毕后自动运行验证检查，输出安装总结表：

```
✅ Ubuntu 24.04 (noble) - amd64
✅ APT Mirror: mirrors.tuna.tsinghua.edu.cn
✅ Locale: en_US.UTF-8
✅ Base tools: curl git wget telnet ping mtr ✓
✅ Zsh 5.9 + Zinit ✓
✅ Starship v1.x.x ✓
✅ JetBrains Mono Nerd Font ✓
✅ Go 1.24.x ✓ (GOROOT=/usr/local/go)
✅ Node.js v22.x.x ✓ (fnm)
✅ npm registry: registry.npmmirror.com
```

### Manual Verification

1. 重新打开 WSL 终端，确认 Zsh + Starship 启动正常
2. Windows Terminal 中设置字体为 "JetBrainsMono Nerd Font"
3. 验证 `go version`、`node --version`、`npm --version` 输出
4. 验证 `bat`、`eza`、`fzf`、`rg` 等工具可用