创建第一个Nuxt v4.x 应用

文章目录

[01 准备阶段](#01 准备阶段)
[02 创建项目](#02 创建项目)
[03 第一个页面](#03 第一个页面)
- [3.1 最简单的使用](#3.1 最简单的使用)
- [3.2 配合页面使用](#3.2 配合页面使用)
- [3.3 配合布局使用](#3.3 配合布局使用)
[04 基础配置](#04 基础配置)
- [4.1 配置 git 大小写敏感](#4.1 配置 git 大小写敏感)
- [4.2 配置 Prettier](#4.2 配置 Prettier)
[05 更多信息](#05 更多信息)

01 准备阶段

Node.js - 20.x 或更高版本（但我们推荐使用活跃的 LTS 版本，确保使用偶数版本20 等）
文本编辑器 - 没有特定的 IDE 要求，但我们推荐 Visual Studio Code 搭配**官方 Vue 扩展（之前称为 Volar）**或 WebStorm，以及其他 JetBrains IDE，它们开箱即用提供出色的 Nuxt 支持
终端 - 用于运行 Nuxt 命令

02 创建项目

打开终端使用以下命令创建一个新的启动项目：（如果使用 Visual Studio Code，可以打开一个集成终端）

bash 复制代码

$ npm create nuxt <project-name>
或
$ yarn create nuxt <project-name>
或
$ pnpm create nuxt <project-name>
或
$ bun create nuxt <project-name>

开始创建（本篇文章使用 pnpm ，创建项目名称为 my-nuxt-project）

bash 复制代码

$ pnpm create nuxt my-nuxt-project

        .d$b.
       i$$A$$L  .d$b
     .$$F` `$$L.$$A$$.
    j$$'    `4$$:` `$$.
   j$$'     .4$:    `$$.
  j$$`     .$$:      `4$L
 :$$:____.d$$:  _____.:$$:
 `4$$$$$$$$P` .i$$$$$$$$P`

ℹ Welcome to Nuxt!
ℹ Creating a new project in my-nuxt-project.

# 使用哪个包管理器
❯ Which package manager would you like to use?
○ npm
● pnpm (current)
○ yarn
○ bun
○ deno

# 是否初始化git仓库
❯ Initialize git repository?
● Yes / ○ No

# 是否安装官方模块
❯ Would you like to install any of the official modules?
● Yes / ○ No

# 选择模块安装（上下/左右移动，空格选中/取消选中，回车保存）
❯ Pick the modules to install:
# 基于文件的 CMS 内容管理系统，支持 Markdown、YAML、JSON 格式的内容管理，允许将内容文件作为数据源使用
◻ @nuxt/content -- The file-based CMS with support for Markdown, YAML, JSON
# 专为Nuxt项目设计的ESLint集成工具，自动检查代码风格和潜在错误，提供项目感知、易于使用、可扩展且面向未来的代码质量检查
◻ @nuxt/eslint -- Project-aware, easy-to-use, extensible and future-proof ESLint integration
# 自定义网络字体模块，专注于性能优化，帮助添加和管理网页字体
◻ @nuxt/fonts -- Add custom web fonts with performance in mind
# 应用程序提示模块，显示关于应用各个方面（如性能、安全性等）的优化建议和提示
◻ @nuxt/hints -- Nuxt module that shows hints for aspects of your application such as Performance, Security, and more!
# 图标模块，集成了 Iconify 图标库，提供超过20万+现成可用的图标资源
◻ @nuxt/icon -- Icon module for Nuxt with 200,000+ ready to use icons from Iconify
# 图像处理模块，支持渐进式处理、懒加载、调整大小以及多种图像提供商支持
◻ @nuxt/image -- Add images with progressive processing, lazy-loading, resizing and providers support
# 第三方脚本管理模块，在不牺牲性能的前提下添加和管理第三方脚本
◻ @nuxt/scripts -- Add 3rd-party scripts without sacrificing performance
# Nuxt 测试工具集，为 Nuxt 应用程序提供专门的测试工具和实用程序
◻ @nuxt/test-utils -- Test utilities for Nuxt
# Nuxt 官方推出的 UI 组件库，基于 Reka UI 和 Tailwind CSS 构建，提供丰富的界面组件
◻ @nuxt/ui -- The Intuitive UI Library powered by Reka UI and Tailwind CSS

# 成功创建后，进入该文件夹下，使用 pnpm run dev 可以运行项目
✨ Nuxt project has been created with the v4 template. Next steps:
 › cd my-nuxt-project
 › Start development server with pnpm run dev

若不确定如何选择官方模块，推荐可以先勾选 @nuxt/eslint、@nuxt/icon、@nuxt/image 和 @nuxt/ui，后期也可以手动添加其他模块：

bash 复制代码

# 例如添加模块 @nuxt/content 如下：
$ npm install @nuxt/content
或
$ pnpm install @nuxt/content
或
···

运行项目（http://localhost:3000/）

bash 复制代码

# 移动到项目文件夹下
$ cd my-nuxt-project

# 安装依赖
$ pnpm i

# 运行项目
$ pnpm run dev

> my-nuxt-project@ dev /my-nuxt-project
> nuxt dev

Nuxt 4.2.1 (with Nitro 2.12.9, Vite 7.2.4 and Vue 3.5.25)

  ➜ Local:    http://localhost:3000/
  ➜ Network:  use --host to expose

  ➜ DevTools: press Shift + Option + D in the browser (v3.1.1)
  
ℹ Nuxt Icon server bundle mode is set to local
✔ Vite client built in 37ms
✔ Vite server built in 25ms
✔ Nuxt Nitro server built in 418ms
ℹ Vite server warmed up in 1ms
ℹ Vite client warmed up in 2ms
···

03 第一个页面

3.1 最简单的使用

在 Nuxt 中，pages/ 目录是可选的。如果不存在该目录，Nuxt 将不会包含 vue-router 依赖。（这在构建不需要路由的落地页或应用时非常有用）

app/app.vue

javascript 复制代码

<template>
  <h1>Hello World！</h1>
</template>

3.2 配合页面使用

当项目有 pages/ 目录时，需要使用 <NuxtPage> 组件来显示当前页面：（若不存在 pages/ 目录，则需要在 app/ 下新建目录 pages）

app/app.vue

javascript 复制代码

<template>
  <NuxtPage />
</template>

还可以直接在app.vue中定义应用的通用结构：（请记住，app.vue 是 Nuxt 应用的主组件。在其中添加的任何内容（JS和CSS）都将是全局的，并会包含在每个页面中）

app/app.vue

javascript 复制代码

<template>
  <header>
    页眉内容
  </header>
  <NuxtPage />
  <footer>
    页脚内容
  </footer>
</template>

创建第一个页面，访问 http://localhost:3000/HelloWorld，就能看到刚创建的页面。（Nuxt 会根据 pages 目录自动生成路由，无需其他配置）

app/pages/HelloWorld.vue

javascript 复制代码

<template>
  <h1>Hello World！</h1>
</template>

了解更多关于如何使用 pages/ 目录构建页面的信息。

3.3 配合布局使用

当应用需要为不同页面使用不同布局时，可以使用 layouts/ 目录配合 <NuxtLayout> 组件，它支持定义多个布局并按页面应用它们。

app/app.vue

javascript 复制代码

<template>
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>

了解更多关于如何使用layouts/目录构建布局的信息。

04 基础配置

4.1 配置 git 大小写敏感

新项目记得配置 git 大小写敏感

bash 复制代码

$ git config core.ignorecase false

4.2 配置 Prettier

在项目中配置 Prettier 和 ESLint，使它们协同工作并在保存时自动修复代码格式。（以 Visual Studio Code 为例）

新增 .prettierrc（my-nuxt-project/.prettierrc）

json 复制代码

{
  "semi": true, // 在每条语句末尾添加分号
  "singleQuote": true, // 使用单引号而不是双引号
  "tabWidth": 2, // 使用2个空格作为缩进
  "trailingComma": "es5", // 在对象和数组中使用尾随逗号（ES5支持）
  "printWidth": 80, // 指定每行最大字符数
  "bracketSpacing": true, // 在对象括号之间添加空格
  "arrowParens": "always", // 单参数箭头函数参数周围使用圆括号，例如: (x) => x
  "endOfLine": "lf" // 使用LF作为换行符
}

新增 VS Code 设置文件 settings.json（my-nuxt-project/.vscode/settings.json ），若已在 VS Code 的设置中配置了全局的 settings.json 则可以忽略该步骤

json 复制代码

{
 // 在保存文件时自动格式化代码
 "editor.formatOnSave": true,
 // 设置 Prettier 作为默认的代码格式化工具
 "editor.defaultFormatter": "esbenp.prettier-vscode",
 // 配置保存时执行的代码操作
 "editor.codeActionsOnSave": {
   // 在保存时运行 ESLint 的自动修复功能
   "source.fixAll.eslint": "explicit"
 },
 // 指定需要 ESLint 验证的文件类型
 "eslint.validate": [
   "javascript",
   "typescript",
   "vue"
 ],
 // 为 Vue 文件设置默认格式化器
 "[vue]": {
   "editor.defaultFormatter": "esbenp.prettier-vscode"
 },
 // 为 JavaScript 文件设置默认格式化器
 "[javascript]": {
   "editor.defaultFormatter": "esbenp.prettier-vscode"
 },
 // 为 TypeScript 文件设置默认格式化器
 "[typescript]": {
   "editor.defaultFormatter": "esbenp.prettier-vscode"
 }
}

更新 eslint.config.mjs 配置文件以集成 Prettier：（my-nuxt-project/eslint.config.mjs）

javascript 复制代码

// @ts-check
import withNuxt from './.nuxt/eslint.config.mjs'
import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';

export default withNuxt(
  eslintPluginPrettierRecommended,
  {
    rules: {
      // 其他自定义规则可以放在这里
    }
  }
)

更新 package.json 来安装所需的依赖：

json 复制代码

{
  "name": "my-nuxt-project",
  "type": "module",
  "private": true,
  "scripts": {
    "build": "nuxt build",
    "dev": "nuxt dev",
    "generate": "nuxt generate",
    "preview": "nuxt preview",
    "postinstall": "nuxt prepare",
    "lint": "eslint .",
    "lint:fix": "eslint . --fix"
  },
  "dependencies": {
    "@nuxt/eslint": "1.11.0",
    "@nuxt/image": "2.0.0",
    "@nuxt/ui": "4.2.1",
    "eslint": "^9.39.1",
    "nuxt": "^4.2.1",
    "typescript": "^5.9.3",
    "vue": "^3.5.25",
    "vue-router": "^4.6.3"
  },
  "devDependencies": {
    "eslint-plugin-prettier": "^5.2.3",
    "prettier": "^3.4.2"
  }
}

现在要使这些配置生效，需要执行以下步骤：

安装新增的依赖 npm install --save-dev eslint-plugin-prettier prettier 或者 npm i
重启 VS Code（确保新的 ESLint 和 Prettier 配置被加载）
确保在 VS Code 中安装了 "Prettier - Code formatter" 扩展（esbenp.prettier-vscode）

配置完成后，当保存文件时会发生以下情况：

Prettier 会自动格式化代码（引号、缩进、分号等）
ESLint 会处理更复杂的代码质量问题
两者协同工作，不会产生冲突

05 更多信息

Nuxt 是一个免费且开源框架，以直观和可扩展的方式，基于 Vue.js 创建类型安全、高性能且适用于生产环境的完整堆栈网页应用和网站。更多详细信息请前往 Nuxt v4.0 官网发现吧！