安装与创建项目
为什么需要了解安装流程？
虽然 npx nuxi@latest init my-app 一行命令就能创建项目，但了解每个步骤在做什么，能帮你在遇到问题时快速定位。比如：
- 首次启动慢是为什么？因为要生成类型声明。
- 为什么有些依赖装不上？可能是 Node 版本太低。
- 创建项目时该选哪个包管理器？不同选择会影响后续开发体验。
环境要求
| 工具 | 最低版本 | 推荐版本 | 为什么 |
|---|---|---|---|
| Node.js | 18.20.0+ | 20.x LTS | Nuxt 4 使用了较新的 JS 特性，旧版 Node 不支持 |
| 包管理器 | npm 10+ | 最新版 | 影响安装速度和依赖解析 |
| 编辑器 | - | VS Code + Vue 官方插件 | 语法高亮、类型提示、自动补全 |
如何检查 Node 版本？
终端运行 node -v。如果版本低于 18，去 nodejs.org 下载 LTS 版本。推荐用 nvm 管理多个 Node 版本。
包管理器怎么选？
npm：Node.js 自带，无需额外安装，适合新手pnpm：速度快、磁盘占用小，社区推荐bun：最新最快，但生态兼容性可能有问题yarn：老牌工具，现在优势不大
新手建议用 npm
熟悉后可以切 pnpm。
创建新项目
使用 nuxi CLI 创建项目：
npx nuxi@latest init my-app这行命令做了什么？
npx：临时下载并执行一个 npm 包，不需要全局安装nuxi@latest：使用最新版本的 Nuxt CLI 工具init my-app：在当前目录下创建名为my-app的项目
你也可以用 pnpm dlx nuxi@latest init my-app 或 bunx nuxi@latest init my-app。
创建过程交互选项
运行 nuxi init 后，CLI 会依次询问以下选项：
① 选择模板
◆ Which template would you like to use?
│ ○ content – Content-driven website
│ ● minimal – Minimal setup for Nuxt 4 (recommended)
│ ○ module – Nuxt module
│ ○ ui – App using Nuxt UI
│ ○ v5-nightly – Minimal setup for Nuxt 5 Nightly
└| 模板 | 说明 | 适合谁 |
|---|---|---|
minimal | 最小化 Nuxt 4 项目（默认推荐） | 大多数项目，从零开始开发 |
content | 基于 @nuxt/content 的内容驱动网站 | 博客、文档站、知识库 |
ui | 集成 @nuxt/ui 的应用 | 需要完整 UI 组件库的项目（管理后台、SaaS） |
module | Nuxt 模块开发脚手架 | 想开发 Nuxt 模块给其他人用 |
v5-nightly | Nuxt 5 每夜版 | 尝鲜最新特性，不适合生产 |
新手选择 minimal
如果你需要 UI 组件库，选 ui 模板会自动配置 @nuxt/ui（包含 TailwindCSS、按钮、表单、弹窗等 110+ 组件）。如果以后想加 UI 库，也可以手动安装。
② 选择包管理器
◆ Which package manager would you like to use?
│ ○ npm
│ ○ pnpm
│ ● yarn
│ ○ bun
└| 包管理器 | 优点 | 缺点 | 推荐场景 |
|---|---|---|---|
npm | Node.js 自带，零配置 | 安装速度中等 | 新手首选 |
pnpm | 速度快、磁盘占用小（硬链接） | 某些包兼容性问题 | 有经验者推荐 |
yarn | 经典工具，稳定 | 优势已不明显 | 已有 yarn 习惯 |
bun | 最快 | 生态兼容性可能有问题 | 追求极致速度 |
INFO
️ 选择后不要混用：如果你选了 npm 后续统一用 npm install/npm run dev；选了 pnpm 就统一用 pnpm install/pnpm dev。混用会导致依赖冲突
③ 是否初始化 Git
◆ Initialize git repository?
│ ● Yes / ○ No
└推荐选 Yes
Git 版本控制是开发的基本功：
- 代码改坏了可以回退
- 多人协作必须用 Git
- 部署到 Vercel/Netlify 等平台需要 Git
如果选了 No，之后也可以手动初始化：git init && git add . && git commit -m "init"
④ 是否安装模块（可选）
CLI 可能会询问是否安装常用模块（取决于模板和版本），如 TailwindCSS、Pinia 等。
新手可以跳过
后续根据需要手动安装。用一行命令即可添加：
npx nuxi module add tailwindcss # 添加 TailwindCSS
npx nuxi module add pinia # 添加 Pinia 状态管理跳过交互式选项
如果你不想逐个选择，可以通过命令行参数直接指定：
# 指定模板
npx nuxi@latest init my-app --template minimal
# 指定包管理器
npx nuxi@latest init my-app --packageManager pnpm
# 指定要安装的模块（逗号分隔）
npx nuxi@latest init my-app --modules @nuxt/ui,@pinia/nuxt
# 跳过依赖安装（之后手动 npm install）
npx nuxi@latest init my-app --no-install
# 初始化 Git
npx nuxi@latest init my-app --gitInit
# 强制覆盖已存在的目录
npx nuxi@latest init my-app --force
# 离线模式（使用缓存的模板）
npx nuxi@latest init my-app --offline常用参数汇总
| 参数 | 说明 | 示例 |
|---|---|---|
-t, --template | 指定模板 | --template ui |
--packageManager | 指定包管理器 | --packageManager pnpm |
-M, --modules | 安装模块（逗号分隔） | --modules @nuxt/ui |
--gitInit | 初始化 Git 仓库 | --gitInit |
--no-install | 跳过依赖安装 | --no-install |
-f, --force | 强制覆盖已有目录 | --force |
--offline | 离线模式 | --offline |
--shell | 安装完后进入项目目录 | --shell |
项目初始化流程
nuxi init 完成后，项目已经创建好了（依赖也已自动安装）。接下来只需：
1. 进入项目目录
cd my-app2. 项目默认结构（Nuxt 4）
不同模板的默认结构略有不同，以 minimal 模板为例：
my-app/
├── app/ # 应用主目录（Nuxt 4 新结构）
│ ├── pages/
│ │ └── index.vue # 首页
│ └── app.vue # 根组件
├── server/
│ └── api/
│ └── hello.ts # 示例 API
├── nuxt.config.ts # Nuxt 配置文件
├── package.json
├── tsconfig.json
└── .gitignoreui 模板的额外内容：
my-app/
├── app/
│ ├── pages/
│ │ └── index.vue # 包含 UI 组件示例的首页
│ └── app.vue # 包含 NuxtLayout + NuxtPage
├── nuxt.config.ts # 已配置 @nuxt/ui 模块
├── tailwind.config.ts # TailwindCSS 配置（@nuxt/ui 内置）
└── ...每个文件/目录的作用
app/：你写前端代码的地方（页面、组件、布局等）server/：你写后端代码的地方（API、中间件等）nuxt.config.ts：Nuxt 的"控制中心"，所有全局配置都在这里package.json：项目信息、依赖列表、运行脚本tsconfig.json：TypeScript 配置（Nuxt 自动管理，一般不需要改）
Nuxt 3 vs Nuxt 4
Nuxt 3 中 pages/、components/ 等目录直接放在项目根目录；Nuxt 4 统一放入 app/ 目录，结构更清晰。
3. 启动开发服务器
npm run devINFO
️ 如果使用 pnpm：命令为 pnpm dev 使用 yarn 则为 yarn dev。请使用与你创建项目时选择的包管理器一致的命令
首次启动会自动运行 nuxt prepare 生成 .nuxt/ 目录和类型声明。
为什么首次启动慢？
Nuxt 需要：
- 扫描你的项目结构，生成路由和自动导入信息
- 生成 TypeScript 类型声明
- 启动 Vite 开发服务器
后续启动会快很多，因为这些信息已被缓存。
4. 构建和预览（部署前）
# 构建生产版本
npm run build
# 本地预览生产版本
npm run preview开发模式 vs 生产模式的区别
- 开发模式（
dev）：有 HMR 热更新、源码映射、详细错误提示，方便调试 - 生产模式（
build）：代码压缩、优化、去除调试信息，运行更快
你平时开发用 dev，部署上线用 build。
为什么要预览？
有些问题只在生产模式出现（比如代码压缩导致的 bug），preview 让你在本地就能看到生产版本的效果。
常用项目脚本
package.json 中默认包含以下脚本：
{
"scripts": {
"dev": "nuxt dev", // 启动开发服务器
"build": "nuxt build", // 构建生产版本
"generate": "nuxt generate", // 静态站点生成（SSG）
"preview": "nuxt preview", // 预览生产版本
"postinstall": "nuxt prepare" // 安装后自动生成类型
}
}| 命令 | npm | pnpm | yarn | 何时用 |
|---|---|---|---|---|
| 开发服务器 | npm run dev | pnpm dev | yarn dev | 日常开发 |
| 构建生产版本 | npm run build | pnpm build | yarn build | 准备部署 |
| 静态站点生成 | npm run generate | pnpm generate | yarn generate | 纯静态网站 |
| 预览构建结果 | npm run preview | pnpm preview | yarn preview | 本地测试 |
postinstall 是什么？
这是 npm 的钩子脚本，在 npm install 完成后自动执行 nuxt prepare，确保类型声明是最新的。你不需要手动运行它。
在线体验
如果不想在本地创建项目，可以直接在浏览器中体验：
适合场景
想快速试一下 Nuxt 的功能，或者电脑上没装 Node.js。但不适合长期开发（浏览器编辑器体验有限）。
升级已有项目
如果你已有 Nuxt 3 项目想升级到 Nuxt 4：
npx nuxt upgrade --force或使用自动迁移工具：
npx codemod@latest nuxt/4/migration-recipe常见问题
创建项目时报错 "command not found: npx"
说明你的 Node.js 版本太老或没安装。升级 Node.js 到 18+ 即可。
运行 nuxt dev 报错 "bash: nuxt: command not found"
nuxt 是项目本地依赖，不是全局命令。使用 npm run dev 或 npx nuxt dev 代替。详见 03-开发服务器。
依赖安装很慢
换国内镜像源：
# npm
npm config set registry https://registry.npmmirror.com
# pnpm
pnpm config set registry https://registry.npmmirror.com
# yarn
yarn config set registry https://registry.npmmirror.comTIP
如果 nuxi init 时安装依赖很慢 可以先 Ctrl+C 取消，然后用 --no-install 跳过安装，手动换源后再安装
npx nuxi@latest init my-app --no-install
cd my-app
npm config set registry https://registry.npmmirror.com
npm install启动后页面打不开
- 确认终端没有报错
- 确认访问的是
http://localhost:3000（不是其他端口） - 如果端口被占用，用
npx nuxt dev --port 3001换个端口
知识脉络
Nuxt 简介 → 你在这里：安装与创建项目
│
├─→ 下一步：开发服务器
│
└─→ 相关：项目配置（了解 nuxt.config.ts）