安装与创建项目
创建一个 Nuxt 4 项目只要一条命令。本章介绍环境要求、官方 CLI、手动安装，以及后面一直会用到的目录结构。
环境要求
- Node.js 20.x 或更新版本，建议使用偶数 LTS（20、22、……）。
- 终端 + 编辑器：VS Code + Vue (Volar) 插件或 WebStorm 都行。
- Windows 用户建议：用 WSL，并用
127.0.0.1代替localhost，可避免 DNS 慢和 HMR 抖动。
用 CLI 初始化
# pnpm
pnpm create nuxt@latest my-app
# npm
npm create nuxt@latest my-app
# bun
bun create nuxt@latest my-app
CLI 会询问包管理器、Linter、CSS 方案等。选完后：
cd my-app
pnpm install
pnpm dev -o # -o 会自动打开浏览器
访问 http://localhost:3000 就能看到默认欢迎页。
手动安装
想搞清楚底层发生了什么，就从零开始：
mkdir my-app && cd my-app
pnpm init
pnpm add -D nuxt
在 package.json 中加入脚本：
{
"scripts": {
"dev": "nuxt dev",
"build": "nuxt build",
"preview": "nuxt preview"
}
}
新建 app.vue：
<template>
<div>Hello Nuxt 4</div>
</template>
pnpm dev 启动后就能访问 http://localhost:3000，其余细节 Nuxt 会自动处理。
目录结构
Nuxt 4 推荐的目录布局：
my-app/
├── app/
│ ├── app.vue # 根组件
│ ├── pages/ # 文件式路由
│ ├── layouts/ # 布局
│ ├── components/ # 自动导入的组件
│ ├── composables/ # 自动导入的组合式函数
│ ├── utils/ # 自动导入的工具
│ ├── middleware/ # 路由中间件
│ ├── plugins/ # 客户端/服务端插件
│ └── assets/ # 需要 Vite 处理的资源
├── public/ # 原样托管到 /
├── server/
│ ├── api/ # /api/* 接口
│ ├── middleware/ # 服务端中间件
│ └── plugins/ # Nitro 插件
├── nuxt.config.ts # 框架配置
├── tsconfig.json # 从 .nuxt/ 继承
└── package.json
两点特别要记住：
app/下的所有内容都被自动导入 —— 自己的组件与 composable 都不需要写import。server/跑在 Nitro 上，不是 Vite。服务端接口都写在这里。
开发服务器
pnpm dev # 启动 dev 服务器
pnpm dev -o # 自动打开浏览器
pnpm dev --port 4000 # 换端口
HMR、TypeScript、Vite、Nitro dev server 全部自动配好。
nuxt.config.ts 基本用法
最小 nuxt.config.ts 一般会打开 DevTools、注册模块：
export default defineNuxtConfig({
devtools: { enabled: true },
modules: ['@pinia/nuxt', '@nuxtjs/tailwindcss'],
})
这点配置就足够开工了。下一章会细讲环境变量覆盖、runtimeConfig 与 app.config 区别、TypeScript 集成等内容，但到这一步已经可以写页面。
写下第一页
把 app.vue 改成：
<template>
<NuxtLayout>
<NuxtPage />
</NuxtLayout>
</template>
新建 app/pages/index.vue：
<template>
<section>
<h1>Hello Nuxt 4</h1>
<p>30 秒体验文件式路由。</p>
</section>
</template>
路由完全由 app/pages/ 生成，不需要任何路由表。
