环境准备

写代码前先把工具备齐，这步省下的麻烦后面会加倍还回来。Nuxt 对环境的要求不高，但有两条红线：Node 版本不能太低，包管理器选一个用到底。

2-1

Nuxt 4 要求 Node.js 20 或更高版本，官方推荐使用 22.x 及以上的活跃 LTS（长期支持）版本。原因很简单：Nuxt 底层的 Nitro、Vite 都用到了较新的 JavaScript 特性，老版本 Node 跑不起来或会报奇怪的错。

怎么看自己装了哪个版本？打开终端，敲：

node -v

如果输出版本号低于 20，或者提示找不到命令，就需要先装 Node。最省心的办法是去 nodejs.org 下载 LTS 安装包，一路下一步即可。装完重开终端再敲一次 node -v 确认。

2-2

「包管理器」是帮你下载、安装、管理第三方依赖的工具。Nuxt 项目不强制用哪一个，但一个项目最好从头到尾只用一种，混用会导致 node_modules 依赖树不一致、出各种灵异问题。

下面三个是最主流的选择：

包管理器	命令示例	特点
npm	npm install	Node 自带，无需额外安装，最稳但速度一般
pnpm	pnpm install	速度快、磁盘占用小，靠硬链接复用依赖，社区越来越流行
yarn	yarn install	老牌选择，生态成熟，经典项目多见

官方脚手架同时支持三种（以及 bun、deno）。如果你拿不准，用 npm 最省事，因为它随 Node 一起装好了。想追求更快的安装速度和更干净的依赖，推荐 pnpm。

装好之后，验证一下版本：

npm -v
pnpm -v
yarn -v

只要其中一个能正常输出版本号，就说明环境就绪。

2-3

写 Nuxt 没有强制编辑器，但体验差距很大。官方强烈推荐两款：

• Visual Studio Code（VS Code）：免费、轻量、插件丰富，是绝大多数前端开发者的选择。
• WebStorm（及 JetBrains 系列 IDE）：付费但开箱即用，对 Nuxt/Vue 的支持几乎零配置。

如果你还没装编辑器，直接装 VS Code 就够了。从官网 code.visualstudio.com 下载，安装时建议勾选「添加到 PATH」，这样能在终端用 code . 命令直接打开项目。

2-4

光有编辑器还不够。要让 Vue 的语法高亮、类型提示、错误检查都工作起来，必须装 Vue 官方语言工具插件（以前叫 Volar，现在在 VS Code 扩展市场搜 Vue - Official）。

在 VS Code 里按以下步骤安装：

1. 打开扩展面板（左侧方块图标，或快捷键 Ctrl+Shift+X）。
2. 搜索 Vue Language Tools 或 Vue - Official。
3. 找到由 Vue 团队发布的那个，点「安装」。

装完后，所有 .vue 文件都会有正确的高亮和补全。如果你用 Neovim、WebStorm 等其他编辑器，也都提供了对应的 Vue Language Server 支持，按官方指南配置即可。

2-5

如果你在 Windows 上开发，有两个坑提前避开：

• 慢 HMR（热更新）：如果感觉改代码后页面刷新很慢，试试把项目放进 WSL（Windows 子系统 Linux）里跑，性能通常会明显好转。
• 本地访问用 127.0.0.1 而非 localhost：在 Windows 上用 127.0.0.1:3000 打开开发服务器，比 localhost:3000 加载更快，能避开 Windows 的 DNS 解析慢问题。

2-6

最后确认你有一个能跑命令的终端。Nuxt 的所有操作——创建项目、启动开发服务器、构建——都是通过终端命令完成的。

• Windows：可以用系统自带的「命令提示符」或「PowerShell」，也可以装一个更现代的终端（如 Windows Terminal）。
• macOS：用自带的「终端」App 即可。
• VS Code 内部也集成了终端（快捷键 Ctrl+`），写代码时不用切窗口，很方便。

2-7

环境到底配没配好，跑几个命令就知道了。挨个敲一遍，对照下面的预期：

• node -v 应输出版本号且 ≥ 20。
• 你选的包管理器 npm -v / pnpm -v / yarn -v 至少有一个出数字。
• 终端输入 code -v（装了 VS Code 且加了 PATH 的话）能看到版本号；若提示找不到命令，说明 VS Code 没加进 PATH，后面用 code . 打开项目会失败，需要重装时勾选「添加到 PATH」，或用完整路径启动它。

三样都正常，环境这关就算过了。下一章我们拿它真正创建一个 Nuxt 4 项目。

2-7 验证环境是否就绪

装完所有工具后，做一次完整的验证能帮你省去后面排查问题的时间。打开终端，依次运行以下命令，确认每个都输出了合理的版本号：

第一，node -v 应该输出 v20 或更高的版本号。第二，npm -v 会显示 npm 的版本，通常 Node 安装时会一并装好。第三，如果你选了 pnpm，运行 pnpm -v 确认它可用。第四，npx nuxi --version 能正常输出版本号，说明 Nuxt 的脚手架工具已就绪。

如果某一步报错，最常见的原因有三个：一是安装后没重启终端，环境变量还没生效；二是系统 PATH 里没有 Node 的安装路径；三是多个 Node 版本互相冲突。遇到这些情况，先重启终端试试，不行就检查 PATH 设置。

2-8 关于全局安装与项目安装的取舍

有些教程会建议你全局安装 Nuxt 的命令行工具（npm install -g nuxi）。这种做法在早期比较流行，但现在更推荐的做法是在项目里本地安装。本地安装的好处是每个项目用自己版本的工具，不会互相干扰。全局安装则可能在多个项目版本不一致时产生奇怪的问题。

如果你已经在用 npx nuxi 的方式创建和运行项目，那就不需要全局安装任何东西。npx 会自动下载并使用最新版本的 nuxi，用完即弃，不会污染全局环境。这也是 Nuxt 官方推荐的方式。

2-9 常见环境问题速查

配环境的过程中，几乎每个人都会遇到一些奇怪的问题。这里列出几个最常见的，帮你快速排障。

第一个问题：运行 node -v 提示”不是内部或外部命令”。这说明 Node 没有安装成功，或者安装后没有重启终端。先重启终端试试，如果还是不行，去 Node 官网重新下载安装。安装时注意选择 LTS 版本，不要用 Current 版本。

第二个问题：npm install 特别慢或者超时。这通常是网络问题。可以切换到国内镜像源来解决：运行 npm config set registry https://registry.npmmirror.com 切换到淘宝镜像。如果你用 pnpm，对应的命令是 pnpm config set registry https://registry.npmmirror.com。

第三个问题：不同项目需要不同版本的 Node。这时候版本管理器就派上用场了。安装 nvm（Windows 用 nvm-windows）后，你可以用 nvm install 22 安装 Node 22，用 nvm use 20 切换到 Node 20，一行命令搞定版本切换，不同项目互不干扰。

2-10 包管理器的锁文件说明

不管你选了哪个包管理器，安装依赖后都会生成一个”锁文件”。npm 生成的是 package-lock.json，pnpm 生成的是 pnpm-lock.yaml，yarn 生成的是 yarn.lock。这个文件记录了每个依赖的精确版本号和下载地址，确保团队里每个人、每次部署安装的依赖版本完全一致。

锁文件必须提交到 Git 仓库。很多初学者误以为它是自动生成的就不需要提交，这是错误的。没有锁文件，不同时间安装的依赖版本可能不同，导致”你电脑上能跑，我电脑上就报错”的尴尬情况。

另一个常见疑问：能不能同时存在多个锁文件？答案是不应该。如果你之前用 npm 后来切换到 pnpm，记得删掉旧的 package-lock.json，只保留当前包管理器的锁文件。混合锁文件会导致依赖解析混乱。

2-11 编辑器配置的小建议

装好 VS Code 和 Vue 插件之后，还有几个小配置能让开发体验更好。首先是启用”保存时自动格式化”。在 VS Code 的设置里搜索 format on save，勾选这个选项。每次保存文件时代码会自动排版整齐，省去手动格式化的麻烦。

其次是推荐安装 ESLint 插件。Nuxt 项目默认集成了 ESLint，这个插件会在编辑器里实时标出代码规范问题。红色波浪线表示错误，黄色表示警告。写代码的时候就能发现并修正问题，而不是等到提交时才被 CI 拦住。

最后建议开启 VS Code 的”自动保存”功能。设置里搜索 auto save，选择 afterDelay 模式，延迟设为一千毫秒。这样你打字停顿一秒后文件就自动保存了，配合 Nuxt 的热更新，改完代码几乎瞬间就能在浏览器看到效果。

2-12 关于 Git 版本控制的准备

在开始写代码之前，还有一件事值得提前做好：安装并配置 Git 版本控制工具。Nuxt 项目脚手架在创建项目时会自动初始化 Git 仓库，但如果你的电脑上还没装 Git，这一步会失败或者被跳过。

去 Git 官网下载安装后，在终端设置你的名字和邮箱。这两个信息会出现在每次提交记录里，是 Git 识别作者的方式。名字用真名或昵称都行，邮箱建议用 GitHub 关联的那个。

配置完成后，建议注册一个 GitHub 账号。后面的教程里会用到 GitHub 来托管代码、部署项目。即使你现在还不需要，早注册早熟悉，后面不会手忙脚乱。如果你已经熟悉 Git 和 GitHub，这一步可以跳过。

2-13 网络环境的准备

开发过程中需要频繁下载依赖包，稳定的网络环境很重要。如果你在国内，访问 npm 官方仓库可能比较慢。除了前面提到的切换镜像源，还可以考虑使用代理工具加速网络访问。

另外，有些 npm 包在安装时需要编译原生模块（比如 node-sass），这要求你的电脑上有 C++ 编译工具。Windows 用户可以安装 windows-build-tools，macOS 用户需要安装 Xcode Command Line Tools。遇到安装依赖报错时，先看看错误信息是不是和编译有关，这能帮你快速定位问题。

最后提醒一点：如果你的开发环境在公司内网，可能需要配置代理才能访问外部资源。在终端里设置 HTTP_PROXY 和 HTTPS_PROXY 环境变量，npm 和 pnpm 都会自动读取这些配置。具体值请咨询公司的网络管理员。

2-14 开发环境的硬件建议

Nuxt 开发对硬件的要求不算高，但有几个方面会直接影响你的开发体验。内存方面，建议至少十六 GB。开发时你需要同时运行开发服务器、浏览器、编辑器，有时还要开数据库或 Docker 容器。八 GB 内存勉强能跑，但多开几个应用后就会开始卡顿。

硬盘方面，强烈建议使用固态硬盘。Nuxt 的构建过程涉及大量小文件的读写操作，固态硬盘的速度是机械硬盘的十倍以上。项目依赖安装后的 node_modules 目录可能包含数万个文件，固态硬盘能显著缩短安装和构建时间。

显示器方面，如果条件允许，用一块能放下三个窗口的屏幕：编辑器、浏览器、终端各占一块区域。开发时你需要频繁在这三者之间切换查看效果，屏幕太小的话来回切窗口会浪费很多时间。

2-15 环境就绪后的下一步

到这里，你的开发环境应该已经完全准备好了。回顾一下你现在拥有的东西：一个正确版本的 Node.js 运行时、一个顺手的包管理器、一个配好了 Vue 插件的编辑器、一个能跑命令的终端，以及基本的版本控制和网络配置。

下一章我们将用这些工具创建第一个 Nuxt 4 项目。脚手架会帮你生成项目骨架、安装依赖、配好基本的目录结构。你只需要跟着终端里的提示操作，几分钟就能看到第一个页面跑起来。

如果在环境配置这一步遇到了本章没有覆盖到的问题，不要卡在这里太久。把报错信息复制到搜索引擎里查找，绝大多数环境问题都有前人踩过并分享了解决方案。实在解决不了的，也可以先跳过，等学完后面的章节再回头处理。

还有一个小建议：在正式开始写项目代码之前，花十分钟浏览一下 Nuxt 的官方文档首页。不需要读懂所有内容，只是对框架的整体面貌有个印象。知道有哪些概念、哪些目录、哪些命令，后面学习时就不会觉得完全陌生。官方文档的地址是 nuxt.com/docs，它是英文的，但内容组织得非常清晰，配合翻译工具阅读完全没有问题。