Nuxt 4 入门教程：从安装到第一个页面

Nuxt 4 入门教程：从安装到第一个页面

前言

Nuxt 4 于 2025 年 7 月 15 日正式发布，是一个专注于稳定性的重大版本更新。相比 Nuxt 3，它带来了全新的目录结构、改进的数据获取机制和更好的 TypeScript 支持。

1. 环境准备

1.1 安装 Node.js

Nuxt 4 需要 Node.js 20.x 或更高版本。

检查你的 Node.js 版本：

node -v

如果版本低于 20，请前往 Node.js 官网 下载最新的 LTS 版本。

1.2 选择包管理器

你可以使用以下任意一种包管理器：

npm（Node.js 自带）

pnpm（推荐，更快更省空间）

yarn

bun

安装 pnpm（推荐）：

npm install -g pnpm

2. 创建 Nuxt 4 项目

打开终端，执行以下命令创建新项目：

# 使用 npm

npm create nuxt@latest my-blog

# 或使用 pnpm（推荐）

pnpm create nuxt@latest my-blog

# 或使用 yarn

yarn create nuxt@latest my-blog

# 或使用 bun

bun create nuxt@latest my-blog

创建过程中会询问几个问题：

✔ Which package manager would you like to use?

  选择你喜欢的包管理器（推荐 pnpm）

✔ Initialize git repository?

  是否初始化 Git 仓库（推荐 Yes）

✔ Which modules would you like to install?

  选择要安装的模块（初学者可以先跳过）

3. 项目结构详解

创建完成后，进入项目目录：

cd my-blog

3.1 Nuxt 4 新目录结构

Nuxt 4 引入了全新的目录结构，这是与 Nuxt 3 最大的区别之一：

my-blog/

├── app/                    # 应用代码目录（新增！）

│   ├── components/         # Vue 组件

│   ├── composables/        # 组合式函数

│   ├── layouts/            # 布局组件

│   ├── middleware/         # 路由中间件

│   ├── pages/              # 页面（自动生成路由）

│   ├── plugins/            # 插件

│   └── app.vue             # 根组件

├── server/                 # 服务端代码

│   ├── api/                # API 路由

│   ├── middleware/         # 服务端中间件

│   └── utils/              # 服务端工具函数

├── shared/                 # 共享代码（新增！）

│   ├── types/              # 共享类型定义

│   └── utils/              # 共享工具函数

├── public/                 # 静态资源

├── nuxt.config.ts          # Nuxt 配置文件

├── package.json            # 项目依赖

└── tsconfig.json           # TypeScript 配置

3.2 关键目录说明

目录          作用

app/        存放所有前端应用代码，包括页面、组件、布局等

server/     存放后端 API 和服务端逻辑

shared/   存放前后端共享的代码，如类型定义、工具函数

public/    存放静态资源，会直接复制到构建输出

为什么要用 app/ 目录？

在大型项目中，根目录会积累大量文件夹。新结构将应用代码和配置文件清晰分离，同时为 IDE 提供更好的类型推断。

4. 启动开发服务器

# 使用 npm

npm run dev

# 或使用 pnpm

pnpm dev

启动成功后，你会看到：

Nuxt 4.x.x with Nitro 2.x.x

  ➜ Local:    http://localhost:3000/

  ➜ Network:  http://192.168.x.x:3000/

打开浏览器访问 http://localhost:3000，你会看到 Nuxt 的欢迎页面。

5. 创建第一个页面

5.1 了解 app.vue

app/app.vue 是应用的根组件：

<template>

  <div>

    <NuxtPage />

  </div>

</template>

<NuxtPage /> 是一个特殊组件，用于显示当前路由对应的页面内容。

5.2 创建首页

在 app/pages/ 目录下创建 index.vue：

<template>

  <div class="home">

    <h1>欢迎来到我的博客</h1>

    <p>这是用 Nuxt 4 构建的博客系统</p>

  </div>

</template>

<style scoped>

.home {

  max-width: 800px;

  margin: 0 auto;

  padding: 2rem;

  text-align: center;

}

h1 {

  color: #00dc82;

  font-size: 2.5rem;

}

</style>

保存后，浏览器会自动刷新显示你的首页。

5.3 创建关于页面

在 app/pages/ 目录下创建 about.vue：

<template>

  <div class="about">

    <h1>关于我</h1>

    <p>这是一个使用 Nuxt 4 构建的博客系统演示项目。</p>

    <p>通过这个项目，你将学习到：</p>

    <ul>

      <li>Nuxt 4 的目录结构</li>

      <li>文件系统路由</li>

      <li>数据获取方式</li>

      <li>前后端交互</li>

    </ul>

  </div>

</template>

<style scoped>

.about {

  max-width: 800px;

  margin: 0 auto;

  padding: 2rem;

}

h1 {

  color: #00dc82;

}

ul {

  line-height: 2;

}

</style>

6. 添加导航

修改 app/app.vue，添加导航菜单：

<template>

  <div>

    <header class="header">

      <nav class="nav">

        <NuxtLink to="/" class="logo">我的博客</NuxtLink>

        <div class="nav-links">

          <NuxtLink to="/">首页</NuxtLink>

          <NuxtLink to="/about">关于</NuxtLink>

        </div>

      </nav>

    </header>

    <main>

      <NuxtPage />

    </main>

  </div>

</template>

<style>

* {

  margin: 0;

  padding: 0;

  box-sizing: border-box;

}

body {

  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen,

    Ubuntu, Cantarell, sans-serif;

  color: #333;

  background: #f5f5f5;

}

.header {

  background: white;

  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);

  position: sticky;

  top: 0;

  z-index: 100;

}

.nav {

  max-width: 1200px;

  margin: 0 auto;

  padding: 1rem 2rem;

  display: flex;

  justify-content: space-between;

  align-items: center;

}

.logo {

  font-size: 1.5rem;

  font-weight: bold;

  color: #00dc82;

  text-decoration: none;

}

.nav-links {

  display: flex;

  gap: 2rem;

}

.nav-links a {

  color: #333;

  text-decoration: none;

  transition: color 0.2s;

}

.nav-links a:hover,

.nav-links a.router-link-active {

  color: #00dc82;

}

main {

  min-height: calc(100vh - 60px);

}

</style>

6.1 NuxtLink 组件

<NuxtLink> 是 Nuxt 提供的导航组件，相比普通的 <a> 标签：

客户端导航：不会触发页面完整刷新

自动预取：当链接进入视口时，自动预取目标页面

自动添加 active 类：当前路由的链接会自动添加 router-link-active 类

7. 常用命令

# 启动开发服务器

npm run dev

# 构建生产版本

npm run build

# 预览生产版本

npm run preview

# 生成静态站点

npm run generate

# 检查代码

npm run lint

8. 本章小结

在这一章中，你学习了：

✅ 安装 Node.js 和包管理器

✅ 创建 Nuxt 4 项目

✅ 理解 Nuxt 4 新目录结构

✅ 创建页面和导航

✅ 使用 NuxtLink 组件