WSL 2 + Docker 本地全栈开发环境配置指南

🚀AI浪潮下前端程序员可以很方便地学习全栈项目。当前接手了一个nuxt全栈项目，以此为媒介开始学习。

在 Windows 下进行 Node.js/Nuxt 等现代前端开发，使用 WSL 2 (Windows Subsystem for Linux) 配合 Docker 是目前公认的最佳实践。这能解决诸多 Windows 下的 C++ 依赖编译问题（如 node-gyp、sharp 报错），并提供与服务器生产环境完全一致的执行体验。

阶段一：安装与配置 WSL 2

1. 启用并安装 WSL 2 (Ubuntu)

打开 Windows 的 PowerShell (管理员)，输入：

powershell 复制代码

wsl --install -d Ubuntu

注意：
- 如果系统提示重启，请重启电脑。
- 重启后，若系统没有自动弹出 Ubuntu 终端，请在 Windows "开始"菜单中搜索并打开 Ubuntu。

2. 初始化 Ubuntu 系统

首次打开 Ubuntu 时，会显示 Installing, this may take a few minutes...，请耐心等待，不要按回车。
提示 Enter new UNIX username: 时，输入你想要的用户名（纯小写字母，无空格），回车。
提示 New password: 时，输入密码（输入时屏幕上不会显示任何字符，盲打即可），回车，再确认一次。
看到类似 username@电脑名:~$ 绿色的提示符，代表系统安装成功。

3. 验证 WSL 2 是否生效

回到 Windows PowerShell，输入：

powershell 复制代码

wsl -l -v

确保你的 Ubuntu 对应的 VERSION 是 2。

阶段二：安装 Docker Desktop 并关联 WSL

前往 Docker 官网下载并安装 Docker Desktop for Windows。
安装过程中，务必勾选 Use WSL 2 instead of Hyper-V 选项。
安装完成后启动 Docker Desktop。
进入 Docker Desktop 设置 (右上角 ⚙️ 图标) -> General ，确保 "Use the WSL 2 based engine" 已勾选。
接着点击左侧 Resources -> WSL integration。
确保勾选 "Enable integration with my default WSL distro"。
关键排错点 ：在下方的列表中，必须开启你刚才安装的 Ubuntu 的开关（变蓝）。如果已经开启但后续报错找不到 docker，请尝试关闭后再开启一次。
点击右下角的 Apply & restart。

阶段三：迁移项目到 WSL 内部（🌟 核心性能关键）

⚠️ 极度重要 ：代码必须存放在 WSL 的内部文件系统（Linux 内）中！千万不要把代码留在 Windows 的 D盘 让 Linux 跨系统访问，否则 I/O 性能会极其低下。

在 Ubuntu 终端 中执行：

bash 复制代码

# 进入 Linux 的家目录
cd ~

# 创建 projects 文件夹并进入
mkdir projects
cd projects

# 把 Windows 盘（比如 D 盘）的代码拷贝到当前 Linux 目录下
cp -r /mnt/d/project/ali_3dm_mod .

# (可选) 如果拷贝太慢，可以先在 Windows 下删除项目的 node_modules 文件夹后再执行拷贝

阶段四：在 WSL 中配置 Node.js 环境

在 Ubuntu 终端 中，为了避免网络问题导致下载失败，推荐使用 Git 从国内镜像直接克隆安装 nvm 和 Node.js：

bash 复制代码

# 1. 更新包列表并确保安装了 Git
sudo apt-get update
sudo apt-get install -y git

# 2. 将 nvm 仓库从 Gitee 镜像直接克隆到本地
git clone https://gitee.com/mirrors/nvm.git ~/.nvm

# 3. 切换到稳定的 v0.39.7 版本
cd ~/.nvm
git checkout v0.39.7

# 4. 把 nvm 环境变量写入终端启动配置 (~/.bashrc)
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.bashrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm' >> ~/.bashrc
echo '[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion' >> ~/.bashrc

# 5. 刷新配置文件使 nvm 立刻生效
source ~/.bashrc

# 6. 配置淘宝镜像，极速下载 Node.js 本体（解决下载卡死问题）
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node/

# 7. 安装最新的 Node.js 长期支持版 (LTS) 并设为默认
nvm install --lts
nvm use --lts

# 8. 全局安装 yarn 并配置国内淘宝镜像加速后续依赖下载
npm install --global yarn
yarn config set registry https://registry.npmmirror.com

阶段五：使用 VS Code 开启"WSL 远程开发"模式

我们依然使用 Windows 上的 VS Code 界面，但它的执行核心会切换到 WSL 内。

打开 Windows 的 VS Code。
在扩展商店搜索并安装微软官方插件：WSL。
回到你的 Ubuntu 终端 ，进入项目目录并唤起 VS Code：
bash 复制代码
```
cd ~/projects/ali_3dm_mod
code .
```
此时会打开一个新的 VS Code 窗口。观察其左下角 ，若显示绿色的 >< WSL: Ubuntu 标志，说明远程连接成功！
在 VS Code 中按 Ctrl + ~ 打开内置终端，确认它显示的是 Linux bash 终端，而非 Windows PowerShell。

阶段六：通过 Docker 启动数据库并运行项目

在 VS Code (WSL 模式) 的内置终端 中操作：

1. 启动本地数据库容器

利用项目自带的 docker-compose.yml 启动 MongoDB 和 Redis 服务：

bash 复制代码

docker compose up -d

(Docker 会自动下载所需镜像并在后台运行，此后只要 Docker Desktop 运行，数据库就在运行)

2. 配置环境变量

在项目根目录新建（或编辑）.env 文件，填入 Docker 服务的连接信息：

env 复制代码

# 连接本地 Docker 的 MongoDB
NUXT_MONGODB_URI="mongodb://root:123456@127.0.0.1:27017/mods"

# 连接本地 Docker 的 Redis
REDIS_HOST="127.0.0.1"
REDIS_PASSWORD="your_redis_password"

(注意：请确保账号、密码与你项目里 docker-compose.yml 中定义的变量严格一致)

3. 安装依赖并启动项目

bash 复制代码

# 安装 Node 依赖 (如果刚刚从 Windows 迁移时删除了 node_modules)
yarn install

# 启动开发服务器
yarn dev

🎉 至此，大功告成！ 你现在拥有了一个极其高效、兼容性完美的本地全栈开发环境。

附录：核心概念与原理解析 (Why & How)

为了让你不仅"知其然"，还能"知其所以然"，这里对本教程中涉及的核心技术进行通俗易懂的解释：为什么要这么折腾？它们到底是什么？

1. WSL 2 (Windows Subsystem for Linux 2)

是什么：微软官方推出的"适用于 Windows 的 Linux 子系统"。
原理：它不是以前那种笨重的传统虚拟机（如 VMWare），而是一个高度集成的轻量级微型虚拟机，直接在 Windows 内部运行着真正的 Linux 内核。
为什么要用它 ：
1. 生态兼容性 ：前端和 Node.js 生态（如项目里的图片处理库 sharp）大量依赖 C++ 底层编译。在 Windows 下极易报 node-gyp 错误，而在 Linux 下几乎都是一键安装成功。
2. I/O 性能 ：Node.js 项目动辄产生数万个 node_modules 碎文件。WSL 2 内部的 Linux 文件系统（ext4）处理小文件的读写速度远超 Windows 的 NTFS 系统，编译和热更新（HMR）速度会有质的飞跃。
3. 与生产环境一致：你的代码最终是部署在 Linux 服务器上的，在本地 Linux 环境开发能消灭"换行符冲突(CRLF vs LF)"、"路径大小写不敏感"等 Windows 特有的幽灵 Bug。

2. WSL 远程开发 (VS Code WSL Extension)

是什么：VS Code 的一款官方插件，让你在 Windows 的界面里无缝编写和运行 Linux 里的代码。
原理：典型的"C/S (客户端/服务端) 架构"。它把 VS Code 劈成了两半：UI 界面客户端 跑在你的 Windows 上（让你享受丝滑的图形体验和快捷键），而核心服务进程（包括终端、代码解析、插件运行）全部悄悄注入到了 WSL 的 Linux 系统里。
为什么要用它 ：
如果不这么做，你得在 Linux 里装个笨重的图形桌面，或者忍受在终端黑框框里写代码的痛苦。这个插件让你既享受了 Windows 界面的好用，又"白嫖"了 Linux 的强大环境，做到了"无缝融合"。

3. Docker

是什么：一个开源的"容器化"技术。你可以把它理解为"超级轻量级、用完即焚的软件沙盒"。
原理：它将一个软件（比如数据库）连同它运行所需的所有底层依赖打包成一个"镜像"。运行这个镜像，就成了一个与外部宿主机完全隔离的"容器"。
为什么要用它 ：
1. 不污染宿主机：之前你在 Windows C盘装 MongoDB，卸载时各种残留。用 Docker，数据库被锁在沙盒里，想删除时一行命令连根拔起，干干净净，绝不占用系统垃圾。
2. 版本隔离与统一：无需担心"我的电脑装的是 Mongo 5，你的电脑是 Mongo 6"这种问题。配置文件写好版本号，团队所有人跑起来的环境完全一模一样。
3. 一键拉起 ：不需要去官网找下载链接、点下一步安装、配环境变量。只需一个 docker-compose.yml 配置文件，敲一行 docker compose up -d，所有基础设施瞬间就绪。

4. MongoDB 和 Redis

MongoDB 是什么：一个流行的 NoSQL 数据库，数据以 JSON 文档的形式存储，无需提前设计表结构，极其契合 Node.js/前端开发者的思维习惯。
Redis 是什么：一个将数据全部放在"内存"里的键值对（Key-Value）数据库，速度快得离谱，通常用来做缓存（Cache）、记录用户 Session 或限制 API 访问频率。
为什么要这么配合使用 ：
- 业务架构需要：Nuxt/Node.js 后端需要持久化存储大量业务数据（Mods、游戏信息、评论等），这存放在 MongoDB 中；同时需要极快的速度来响应高频的请求以减轻主库压力，这就需要 Redis 做中间层缓存。
- 系统限制倒逼环境升级 ：Redis 官方根本不支持 Windows！ 以前只能用微软或第三方很久不维护的魔改版，Bug 频出。现在有了 WSL 2 和 Docker，我们可以在 Windows 电脑上直接跑原汁原味的 Linux 版 Redis，彻底解决了兼容性问题。

附录 2：前端视角下的全栈开发架构理解

很多前端开发者在初次接触全栈项目（如 Nuxt/Next.js）时，经常会感到困惑："我以前写 Vue/React 的时候，随便装个 Node.js 就能跑了，为什么现在要搞这么复杂的环境？还要装 Linux 和 Docker？"

这其实是因为全栈项目和纯前端项目在本质上有着巨大的区别。

1. 纯前端项目 vs 全栈(SSR)项目的本质区别

纯前端项目（如普通的 Vue/React/SPA）：
- 本质：纯静态资源生成器。
- 运行机制 ：本地的 Node.js 仅仅参与"打包编译"的过程。打包出来的产物（一堆 HTML/CSS/JS 文件）是纯静态的，你可以把它丢给任何 Web 服务器（比如 Nginx、CDN），甚至直接双击 index.html 就能在浏览器里运行。
- 环境依赖：极低。不需要数据库，不需要服务端运行环境。所以在 Windows 下原生开发完全足够了，出了问题也多半是浏览器兼容性问题。
全栈/SSR 项目（如 Nuxt 3/Node.js）：
- 本质：包含完整前端视图的后端服务程序。
- 运行机制 ：打包后的产物不再是静态文件，而是一个必须在 Node.js 环境中持续运行的服务器程序。当用户访问网站时，这个程序要实时处理网络请求、查询数据库（比如 MongoDB）、读取缓存（比如 Redis），最后在服务器端把数据塞进 HTML 模板里（SSR，服务端渲染），再把完整的 HTML 返回给浏览器。
- 环境依赖：极高。它强依赖操作系统底层的 I/O 能力、数据库服务和缓存服务。

2. 全栈项目必须这么开发吗？可以不配置这些吗？

不一定必须配置，环境永远是为项目需求服务的。

如果你的全栈项目仅仅是作为一个中间层（BFF），去调用别人写好的外部 HTTP API，而不需要自己本地运行数据库和 Redis ，那你完全不需要折腾 WSL 和 Docker，直接在纯 Windows 下运行 yarn dev 即可。

但像 3DM Mod 站 这样的项目，它：

明确使用了 nuxt-mongodb 连接数据库。
明确使用了 Redis 做高速缓存。
用到了 sharp 等涉及底层 C++ 编译的图像处理库。

这时候，如果你坚持在纯 Windows 下开发，就会遇到致命问题：

Redis 官方根本不支持 Windows。
C++ 依赖包在 Windows 下编译经常报 node-gyp 错误。
Windows 开发环境和最终的 Linux 部署环境不一致，容易出现幽灵 Bug（比如大小写不敏感、换行符冲突）。

3. 为什么 WSL 2 + Docker 是最优解？

这套方案巧妙地做到了**"取其精华，去其糟粕"**：

保留了 Windows 的舒适 UI：你依然在使用熟悉的 Windows 系统，用着熟悉的微信、浏览器，以及丝滑的 VS Code 界面。
白嫖了 Linux 的生产力 ：你的代码跑在真正的 Linux 引擎（WSL 2）里，所有针对 Windows 的编译报错、换行符冲突瞬间灰飞烟灭；且 Linux 处理 node_modules 海量小文件的速度远超 Windows。
基础设施"用完即焚" ：通过 Docker，你不需要在 C 盘安装一堆容易残留的数据库软件。只需一行 docker compose up -d，所有依赖服务瞬间拉起；项目结束删掉容器，电脑干干净净。

总结：全栈开发不仅是语言的延伸，更是视角的转变。当你开始编写需要和数据库、操作系统打交道的代码时，把你的本地环境打造成一个"微型 Linux 服务器"，就是最专业、也是最能让你把精力集中在业务代码上的最优解。

WSL 2 + Docker 本地全栈开发环境配置指南

阶段一：安装与配置 WSL 2

1. 启用并安装 WSL 2 (Ubuntu)

2. 初始化 Ubuntu 系统

3. 验证 WSL 2 是否生效

阶段二：安装 Docker Desktop 并关联 WSL

阶段三：迁移项目到 WSL 内部（🌟 核心性能关键）

阶段四：在 WSL 中配置 Node.js 环境

阶段五：使用 VS Code 开启"WSL 远程开发"模式

阶段六：通过 Docker 启动数据库并运行项目

1. 启动本地数据库容器

2. 配置环境变量

3. 安装依赖并启动项目

附录：核心概念与原理解析 (Why & How)

1. WSL 2 (Windows Subsystem for Linux 2)

2. WSL 远程开发 (VS Code WSL Extension)

3. Docker

4. MongoDB 和 Redis

附录 2：前端视角下的全栈开发架构理解

1. 纯前端项目 vs 全栈(SSR)项目 的本质区别

2. 全栈项目必须这么开发吗？可以不配置这些吗？

3. 为什么 WSL 2 + Docker 是最优解？

1. 纯前端项目 vs 全栈(SSR)项目的本质区别