ProjectAGiPrompt/35-黑苹果DELL/3-WSL系统优化/3.1-wsl初始化脚本-实现计划.md

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

1. 命令行接口

# 完整安装（推荐）
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）

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 启用时：

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 等工具可用