如题，这篇是前端开发环境配置精简实用版（适合有配置经验的人，比如曾经配置过，现在需要在其他电脑上安装环境），按顺序阅读即可。

---

第一次配置的新手可以参考（很详细），但更有效的方法是直接将错误信息贴给AI回答。

前端开发环境配置（错误及解决）

另，我在使用AI解惑的时候，误将一些成功的消息（不需要解答）发给了他。这本无伤大雅，但后面在遇到其他问题的时候，因为前面发过成功的信息，更方便AI帮助排除错误原因。

---

这里提醒自己，下次遇到需要这种连续的环境配置过程，也要把一些节点类的成功消息发送给AI，让他知道我进行到了哪一步骤，这样能更快更准确的回答我遇到的问题。

---

前端开发环境配置

组件	推荐理由
Windows Terminal	系统自带，无需安装。 微软官方出品，多标签、GPU 渲染、主题丰富
WSL 2（Ubuntu）	需要下载安装 完整 Bash 环境，兼容所有前端工具链。 所有命令与 macOS/Linux 开发者完全一致，团队协作无障碍。
Node.js + npm/yarn/pnpm（安装在 WSL 内）	Vue工具链 避免 Windows 路径和权限问题

---

为什么不用 Git Bash 或直接在 Windows 装 Node？

• WSL 提供 真正的 POSIX 环境，避免 node_modules 权限错误、路径分隔符（\ vs /）、脚本兼容性等问题。
• 大多数前端构建工具（如 Vite、Webpack、ESBuild）在 Linux 环境下性能更好、更稳定。

---

WSL 2 需要 Windows 10 版本 ≥ 2004（Build 19041+）或 Windows 11

---

查看系统版本

按 Win + R，输入 winver，查看版本号。

---

Windows Terminal

系统自带

---

一、下载 WSL2

1. 以管理员身份打开 PowerShell，运行：
   Powershell

   wsl --install -d Ubuntu

2. 重启电脑。

首次启动会提示创建用户名和密码（记住这个密码，后续要用）。

---

我的备注：这一步并不会要创建用户名和密码。后面安装Linux 发行版时才需要。

---

---

这里有个问题，重启电脑后打不开WSL，打开立即自动关闭。

原因是尚未安装任何 Linux 发行版（如 Ubuntu、Debian 等）

---

安装 Linux 发行版

通过命令一键安装（推荐）
以 普通用户身份（无需管理员）打开 PowerShell 或 CMD

运行以下命令：
wsl --install -d Ubuntu

系统会自动：

• 从 Microsoft Store 下载 Ubuntu
• 安装并初始化
• 提示你创建 用户名和密码（记住这个密码，后续要用）

⏱️ 首次启动可能需要 2~5 分钟，请耐心等待。

---

验证是否成功

安装完成后，在 PowerShell 中运行（验证 WSL 版本）：

wsl -l -v

✅ 正常输出应类似：

Text

1  NAME      STATE      VERSION
2* Ubuntu    Running    2

然后你就可以：

在 Windows Terminal 中打开 Ubuntu
或直接在 PowerShell 中输入 wsl 进入 Linux 环境

💡 小贴士
用户名和密码：
不是你的 Windows 账号！

密码输入时不会显示星号或字符，输完直接回车即可。

默认版本是 WSL 2 吗？
运行 wsl --set-default-version 2 确保使用最新版（性能更好）。

---

二、在 WSL 中配置前端开发环境

1. 更新系统
Bash

sudo apt update && sudo apt upgrade -y

2. 安装 Node.js（推荐使用 nvm 管理版本）
Bash

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重启终端或 source
source ~/.bashrc

# 安装最新 LTS 版 Node.js
nvm install --lts
nvm use --lts

3. 安装包管理器（任选其一）
Bash

npm install -g yarn      # Yarn
# 或
npm install -g pnpm      # pnpm（更快、节省磁盘）

4. 安装 Git（WSL 默认可能没有）
Bash

sudo apt install git -y
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

---

这里遇到了Git 无法从 GitHub 克隆仓库 的问题。

---

解决方法 ：使用代理（如果你在国内或公司网络受限）

GitHub 在部分地区访问不稳定，建议使用 镜像或代理。

直接使用 FastGit 镜像 + wget 组合，成功率最高：

Bash

wget -qO- https://raw.fastgit.org/nvm-sh/nvm/v0.39.7/install.sh | bash

然后 重启终端 或运行：

Bash

source ~/.bashrc

验证安装：

Bash

command -v nvm  # 应输出 "nvm"

---

现在可以看到如下提示

Downloading nvm from git to '/home/mumu/.nvm'

说明 nvm 安装脚本已经开始执行，正在从 GitHub 克隆仓库到 ~/.nvm 目录。

但如果你卡在这个提示很久（超过 2~3 分钟）没反应，或者最终报错（比如之前遇到的 Failure when receiving data from the peer），那很可能是 网络问题导致 Git 克隆超时或失败。

---

出现 Command 'nvm' not found 错误，说明 nvm 已经安装（或部分安装）但未正确加载到当前 shell 环境中。

---

永久配置（根据你用的 shell，这里默认bash）
编辑 ~/.bashrc：

Bash

nano ~/.bashrc

在文件末尾添加：

Bash

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

保存（Ctrl+O → 回车），退出（Ctrl+X）。

然后重载：

Bash

source ~/.bashrc

---

用的是 bash，编辑 ~/.bashrc具体怎么操作

详见推荐的文章，这里简单说一下

• 编辑 ~/.bashrc
  • nano 是一个简单易用的文本编辑器，适合新手。
  • 不要用 vim（除非你熟悉它），否则可能“卡住出不来”。
  • 按键盘上的 ↓ 方向键，一直往下滚动到文件最后。
  • 或者按 Page Down 键快速翻页。

• 添加 nvm 配置

  • 在文件最后一行之后，空一行，然后输入。

• 保存并退出 nano

  • 按键盘 Ctrl + O（英文 O，不是零）→ 这是 “Write Out”（保存）
  • 然后直接按 Enter（确认文件名不变）
  • 再按 Ctrl + X → 退出 nano

• 重新加载 .bashrc

  在终端运行：

  Bash

  source ~/.bashrc

  这会让当前 shell 立即应用新配置。

• 验证 nvm 是否可用

  Bash

  nvm --version

  ✅ 如果显示版本号（如 0.39.7），说明成功！

---

Now using node v24.11.1 (npm v11.6.2)

你已经成功安装并启用了 Node.js v24.11.1（LTS 或 Current 版本）和 npm v11.6.2，说明你的 nvm 配置完全正常！

现在你已具备完整的前端开发运行环境 ✅

---

三、安装现代包管理器（推荐 pnpm）

Bash

npm install -g pnpm

一键获取完整项目代码

• 比 npm/yarn 更快、节省磁盘空间、依赖结构更清晰。

---

四、创建项目目录（保持整洁）

Bash

mkdir -p ~/projects

cd ~/projects

📌 重要提示：将代码放在 WSL 本地路径（如 ~/projects），不要放在 /mnt/c/...，否则可能遇到性能或权限问题。

---

git config --global user.name "Your Name"

是 设置 Git 全局用户名 的标准操作，但其中 "Your Name" 是一个占位符，你需要替换成你真实的名字或昵称。

 这个名字会出现在你所有的 Git 提交记录中，不需要和 GitHub 账号一致，但建议用真实姓名或常用 ID。

Git 提交还需要邮箱，通常建议使用 与 GitHub 关联的邮箱（用于贡献统计）

---

五、初始化一个Vue项目

详见推荐的文章，这里简单说一下。

---

 以上操作配置好了 Node.js、npm/pnpm 和 Git，现在 初始化一个 Vue 3 测试项目，全面验证前端开发环境是否正常工作。

使用官方推荐的 Vite + Vue 模板（速度快、现代化），并用 pnpm（推荐）进行管理。

✅ 步骤 1：进入项目目录

Bash

# 创建并进入项目文件夹（建议放在 WSL 本地路径）
mkdir -p ~/projects
cd ~/projects

📌 不要放在 /mnt/c/...（Windows 盘），避免潜在性能或权限问题。

---

✅ 步骤 2：使用 pnpm 创建 Vue 3 项目

Bash

pnpm create vue@latest my-vue-app

💡 如果你还没安装 pnpm，先运行：

Bash

npm install -g pnpm

---

交互式配置（按需选择）：

系统会提示你选择功能，新手建议如下：

1✔ Project name: … my-vue-app
2✔ Add TypeScript? … No          # 先用 JavaScript 简单测试
3✔ Add JSX Support? … No
4✔ Add Vue Router for Single Page Application development? … Yes  # 推荐选 Yes
5✔ Add Pinia for state management? … Yes                         # 轻量状态管理
6✔ Add Vitest for Unit testing? … No                             # 暂不测
7✔ Add an End-to-End Testing Solution? … No
8✔ Add ESLint for code quality? … Yes                            # 代码规范
9✔ Add Prettier for code formatting? … Yes                       # 自动格式化

按回车确认。

---

✅ 步骤 3：安装依赖并启动开发服务器

Bash

# 进入项目目录
cd my-vue-app

# 安装依赖
pnpm install

# 启动开发服务器
pnpm run dev

---

✅ 步骤 4：验证是否成功

如果一切正常，你会看到类似输出：

1  VITE v5.0.0  ready in 320 ms
2
3  ➜  Local:   http://localhost:5173/
4  ➜  Network: http://192.168.x.x:5173/

---

🔍 在 Windows 浏览器中打开：

在任意浏览器地址栏输入：

http://localhost:5173

---

✅ 你应该看到 Vue 官方欢迎页面，带有 Vue logo、路由链接、Pinia 状态等。

---

💡 WSL 2 支持端口自动转发到 Windows，所以 localhost:5173 在 Windows 浏览器中可直接访问！

---

✅ 步骤 5：简单修改测试热更新（HMR）

1. 打开项目文件（用 VS Code 最佳）：

   Bash

   code .

   需已安装 VS Code + WSL 插件

2. 编辑 src/App.vue，找到 <h1> 标签，改成：

   Vue

   <h1>Welcome to My Vue Test App! 🎉</h1>

3. 保存文件 → 浏览器自动刷新，文字立即更新！

---

✅ 这证明：开发服务器、热更新、文件监听全部正常！

---

🧪 附加验证

检查构建是否成功

Bash

pnpm run build

应生成 dist/ 目录，无报错。

---

检查 Git 是否记录

Bash

git log --oneline -n 3

---

应看到初始化提交（如 feat: initial commit）。

---

也有可能是：

fatal: not a git repository (or any of the parent directories): .git

---

意思是：当前目录（或其上级目录）不是一个 Git 仓库，所以你运行的 Git 命令（比如 git status、git add、git commit 等）无法执行。

---

✅ 这是正常现象！不是 bug

当你在一个全新的项目文件夹（比如刚用 pnpm create vue@latest 创建的 Vue 项目）中，如果创建时没有自动初始化 Git 仓库，就会出现这个提示。

💡 很多脚手架工具（如 Vite）默认会初始化 Git 仓库，但有时可能被跳过（比如你没选 ESLint/Prettier，或网络问题）。

解决方案：初始化 Git 仓库（只需一次）

在你的项目根目录（例如 ~/projects/my-vue-app）运行：

Bash

# 1. 初始化 Git 仓库
git init

# 2. 添加所有文件到暂存区
git add .

# 3. 首次提交
git commit -m "feat: initial commit"

✅ 执行完后，你的项目就变成了一个 Git 仓库，后续所有 Git 命令都能正常使用！

---

📌 验证是否成功

Bash

git status

应显示：

On branch main
nothing to commit, working tree clean

（或类似信息，说明 Git 已识别项目）

---

配置 VS Code（无缝开发体验）

安装官方插件： WSL
在 WSL 中进入项目目录，运行：
Bash
code .

VS Code 会自动在 WSL 环境中打开项目，终端、调试、扩展全部运行在 Linux 下！

---

六、在VS Code 打开 WSL 终端（Ubuntu）

适用于已安装 WSL 插件 的场景。

手动选择终端类型（已有 VS Code 窗口）
如果你已经打开了一个 VS Code 窗口（但不确定是否在 WSL）：

新建终端

在新终端的标签页右侧，点击 终端类型选择器（通常显示 “JavaScript” 或 “pwsh”）
选择：WSL: Ubuntu
 

✅ 之后所有新建终端都会默认使用 WSL。

---

如何确认当前终端是 WSL？
在终端中运行：

Bash

uname -a

✅ WSL 输出类似：
Linux DESKTOP-XXX 5.15.133.1-microsoft-standard-WSL2 ...

或者看提示符：

WSL：mumu@DESKTOP-XXX:~/projects$
Windows：PS C:\Users\mumu>

---

七、vscode 中找不到新建的项目

项目创建在 WSL 文件系统（如 ~/projects/my-vue-app）
但你是在 Windows 文件资源管理器或普通 VS Code 窗口 中查找（这些只能看到 Windows 盘）
 

🔍 正确位置：项目在 WSL 里，不在 C 盘！

当你在 WSL 终端运行：

Bash

mkdir -p ~/projects
cd ~/projects
pnpm create vue@latest my-vue-app

项目实际路径是：

\\wsl$\Ubuntu\home\你的用户名\projects\my-vue-app

💡 这个路径 不能直接在 Windows 资源管理器地址栏输入 C:\... 找到！

打开项目

适用场景：你已在 WSL 中有一个项目
打开 Windows Terminal → Ubuntu
进入你的项目目录：
Bash
cd ~/projects/my-vue-app

输入命令：
Bash
code .

VS Code 会自动：

• 在 WSL 模式 下打开项目
• 左下角显示 “WSL: Ubuntu”
• 再打开终端就是 Ubuntu 终端

---

再后面遇到的错误和安装了zsh有关，这里就不细说了。

不要频繁切换 shell，就用Bash就够了。

zsh: command not found: node

说明你现在使用的是 zsh（而不是 bash），但 nvm 没有在 zsh 中正确加载。

虽然你之前配置了 ~/.bashrc，但 zsh 不会读取 ~/.bashrc！它使用自己的配置文件 ~/.zshrc。
 

为什么会出现这个问题？

场景	原因
你安装了 Oh My Zsh / zsh	系统默认 shell 变成了 zsh
你在 VS Code 中打开终端	VS Code 可能自动使用 zsh
你手动运行了 zsh	切换了 shell，但没配置 nvm

📌 关键点：

bash 读取 ~/.bashrc
zsh 读取 ~/.zshrc
两者配置互不共享！

---

另外：需要先卸载已经安装的node吗

你的情况	是否需要卸载？	建议操作
Node.js 是在 Windows 上通过官网 .msi 安装的	✅ 建议卸载	避免路径冲突、权限问题、WSL/Windows 混用混乱
Node.js 是在 WSL 中用 apt 安装的（如 sudo apt install nodejs）	✅ 建议卸载	版本旧、难升级，nvm 更灵活
Node.js 是在 WSL 中通过 nvm 安装的	❌ 不需要	可直接复用或升级
你还没装 Node.js	❌ 不需要	直接运行一键脚本即可

🎯 强烈建议：所有前端工具（Node.js、npm、pnpm、项目依赖）都统一放在 WSL 环境中管理，不要混用 Windows 和 WSL。