Nuxt4 项目搭建

学习如何搭建标准的企业级 Nuxt4 项目开发环境，掌握从环境准备到项目初始化的完整流程

概述

本文介绍如何搭建一个企业级的 Nuxt 项目开发环境。

🎯 主要目标

搭建标准的 Nuxt4 企业级开发环境
配置完整的工具链和开发流程
实现企业级项目的最佳实践

💡 核心特性

工程化: 基于 TypeScript + ESLint + Prettier + Husky 的完整代码规范体系，确保代码质量和一致性
开发效率: 支持热重载、TypeScript 智能提示，集成 VSCode 开发工具链
可维护性: 采用分层架构设计，支持组件化开发，完善的文档规范和代码注释
可扩展性: 模块化架构设计，支持插件扩展，易于集成第三方服务

🔧 技术栈

类别	技术方案	选型依据	替代方案	适用场景
核心框架	Nuxt4 + Vue3	- 全栈开发能力 - 约定优于配置 - 内置最佳实践 - 活跃的社区生态	Next.js, SvelteKit	需要SSR/SSG的复杂Web应用
开发语言	TypeScript	- 类型安全 - 更好的代码维护性 - 完善的IDE支持	JavaScript, Flow	中大型项目，团队协作开发
状态管理	Pinia	- 轻量级 - 更好的TypeScript支持 - 组合式API友好	Vuex, Redux	需要全局状态管理的应用
UI 框架	TailwindCSS	- 原子化CSS - 快速原型开发 - 高度可定制	Bootstrap, Material UI	需要快速迭代和自定义样式的项目
测试工具	Vitest + Vue Test Utils	- 与Vite深度集成 - 快速测试执行 - 完善的Vue测试支持	Jest, Cypress	需要单元测试和组件测试的项目
构建工具	Vite	- 极速的开发体验 - 原生ESM支持 - 丰富的插件生态	Webpack, Rollup	现代前端项目，追求开发效率

目标: 搭建一个标准的企业级 Nuxt4 项目开发环境，包含完整的工具链和最佳实践配置。

开发环境准备

Node.js 环境要求

Nuxt4 对 Node.js 版本有特定要求，我们需要确保使用正确的版本来保证项目稳定运行。

最低要求

Node.js 18.0.0 或更高版本
支持 ES2022+ 特性
内置 npm 8.0+ 或 yarn 3.0+

Node 版本管理

使用 Node 版本管理工具有以下优势

同时安装和管理多个 Node.js 版本
快速切换不同项目所需的 Node 版本
支持全局和项目级版本配置

nvm node 版本管理

使用 fnm (更快的替代方案)

检查当前版本

# 使用 nvm 管理 Node.js 版本（推荐）
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装最新的 LTS 版本
nvm install --lts
nvm use --lts

# 设置默认版本
nvm alias default node

最佳实践: 建议在项目根目录添加 .nvmrc 文件，指定项目所需的 Node.js 版本，确保团队成员使用一致的开发环境。

包管理器选择

现代前端开发中，包管理器的选择直接影响开发效率和项目性能。我们来对比主流的包管理器：

1. 包管理器对比

特性	npm	yarn	pnpm
性能	中等	较快	最快
磁盘占用	较大	较大	最小
依赖管理	标准	良好	最佳
工作区支持	有限	良好	优秀
企业级特性	基础	良好	优秀

2. 推荐选择：pnpm

企业级推荐: pnpm 是当前最适合企业级项目的包管理器，具有出色的性能和依赖管理能力。

pnpm 优势：

🚀 安装速度快 - 比 npm 快 2-3 倍
💾 节省磁盘空间 - 使用符号链接共享依赖
🔒 严格的依赖管理 - 避免幽灵依赖问题
🎯 Monorepo 支持 - 原生支持工作区

3. 包管理器安装

安装 pnpm

安装 Yarn

# 使用 npm 安装 pnpm
npm install -g pnpm

# 或者使用 curl 安装
curl -fsSL https://get.pnpm.io/install.sh | sh -

# 验证安装
pnpm --version

IDE 配置与推荐插件

IDE 选择建议

优势:

基于 VS Code 的 AI 编程工具
支持自然语言编程对话
代码重构和优化建议
支持离线使用
界面简洁美观

劣势:

部分功能需要付费
AI 模型响应不够稳定

优势:

免费开源,生态丰富
原生支持 Vue 3 和 TypeScript
轻量级,启动快速
丰富的插件市场
内置 Git 集成
智能代码提示和自动补全
支持远程开发

劣势:

部分高级功能需要插件支持
大型项目可能性能略差

优势:

开箱即用的全功能 IDE
强大的重构工具
内置调试器和测试工具
更智能的代码分析
专业的技术支持

劣势:

付费软件
资源占用较大
启动较慢

优势:

AI 智能代码补全
支持多种编程语言
可根据注释生成代码
提供代码建议和解释
与 VS Code 完美集成

劣势:

需要付费订阅
代码质量不稳定
可能涉及版权问题

优势:

中文友好的 AI 编程助手
支持代码生成和优化
提供中文代码解释
免费使用额度
支持私有化部署

劣势:

仅支持阿里云 IDE
功能相对基础
代码建议准确度待提高

优势:

开源免费的 AI 编程助手
支持多种编程语言
离线运行无需联网
代码自动补全和生成
中英双语对话支持

劣势:

模型效果不如商业产品
功能相对基础
社区生态待完善

优势:

轻量级编辑器
启动速度快
支持多种编程语言
界面简洁直观
可扩展性强

劣势:

功能相对基础
插件生态较小
企业级特性支持有限
调试功能较弱

VSCode 插件推荐

Vue Language Features (Volar)

Vue 3 官方推荐的语言服务插件
提供语法高亮、智能提示、代码跳转等核心功能
支持 <script setup> 语法和 TypeScript 集成

TypeScript Vue Plugin

Vue 的 TypeScript 支持插件
提供 .vue 文件的类型检查
增强 IDE 的类型推导能力

Tailwind CSS IntelliSense

Tailwind CSS 智能提示
自动补全样式类名
悬停预览样式效果

ESLint

代码质量检查工具
自动修复代码格式
确保代码风格统一

Prettier

代码格式化工具
支持多种文件类型
与 ESLint 配合使用

GitLens

Git 历史记录可视化
代码行级别的变更追踪
团队协作必备工具

Markdown All in One

Markdown 语法支持
实时预览功能
自动生成目录

Docker

Docker 容器管理
Dockerfile 语法支持
容器状态监控

Thunder Client

轻量级 API 测试工具
类似 Postman 的功能
支持环境变量管理

Jest Runner

单元测试运行工具
测试结果可视化
支持调试测试用例

创建 Nuxt4 项目

使用脚手架搭建项目

Nuxt4 提供了多种项目创建方式，我们推荐使用官方脚手架来确保项目结构的标准化。

项目创建命令

使用 pnpm (推荐)

使用 npm

使用 yarn

# 创建新项目
pnpm create nuxt@latest my-nuxt4-app

# 进入项目目录
cd my-nuxt4-app

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

企业级项目模板

对于企业级项目，我们建议使用自定义模板：

Starter Templates

create-nuxt-app

# 使用企业级模板
npm create nuxt@latest -- -t v4 # 使用 nuxt4 template

cd my-app
pnpm install

项目目录结构详解

Nuxt4 引入了新的目录结构，同时保持与传统结构的兼容性。

1. 传统目录结构

Nuxt 3 传统结构

目录说明

my-nuxt3-app/
├── assets/              # 静态资源
│   ├── css/
│   ├── images/
│   └── fonts/
├── components/          # Vue 组件
│   ├── ui/
│   └── layout/
├── composables/         # 组合式函数
├── content/            # 内容文件
├── layouts/            # 布局组件
├── middleware/         # 中间件
├── pages/              # 页面组件
├── plugins/            # 插件
├── public/             # 静态文件
├── server/             # 服务端代码
│   └── api/
├── stores/             # 状态管理
├── utils/              # 工具函数
├── app.vue             # 根组件
├── nuxt.config.ts      # 配置文件
└── package.json

2. Nuxt4 新目录结构

新特性: Nuxt4 引入了 app/ 目录，提供更清晰的项目组织方式，同时保持向后兼容。

Nuxt 4 新结构

兼容性说明

my-nuxt4-app/
├── app/                 # 应用核心目录 (新)
│   ├── components/      # 组件
│   ├── composables/     # 组合式函数
│   ├── layouts/         # 布局
│   ├── middleware/      # 中间件
│   ├── pages/           # 页面
│   ├── plugins/         # 插件
│   ├── stores/          # 状态管理
│   ├── utils/           # 工具函数
│   ├── app.vue          # 根组件
│   └── router.options.ts # 路由配置
├── assets/              # 静态资源
├── content/             # 内容文件
├── public/              # 静态文件
├── server/              # 服务端代码
├── types/               # 类型定义
├── nuxt.config.ts       # 配置文件
└── package.json

3. 目录结构最佳实践

企业级项目推荐结构：

企业级目录结构

命名约定

my-enterprise-app/
├── app/
│   ├── components/
│   │   ├── ui/           # 基础UI组件
│   │   ├── form/         # 表单组件
│   │   ├── layout/       # 布局组件
│   │   └── business/     # 业务组件
│   ├── composables/
│   │   ├── useAuth.ts    # 认证相关
│   │   ├── useApi.ts     # API相关
│   │   └── useUtils.ts   # 工具函数
│   ├── layouts/
│   │   ├── default.vue   # 默认布局
│   │   ├── auth.vue      # 认证布局
│   │   └── dashboard.vue # 控制台布局
│   ├── middleware/
│   │   ├── auth.ts       # 认证中间件
│   │   └── admin.ts      # 管理员中间件
│   ├── pages/
│   │   ├── auth/         # 认证页面
│   │   ├── dashboard/    # 控制台页面
│   │   └── admin/        # 管理页面
│   ├── plugins/
│   │   ├── api.client.ts # API插件
│   │   └── auth.client.ts# 认证插件
│   └── stores/
│       ├── auth.ts       # 认证状态
│       ├── user.ts       # 用户状态
│       └── app.ts        # 应用状态
├── assets/
│   ├── css/
│   │   ├── main.css      # 主样式
│   │   ├── components.css# 组件样式
│   │   └── utilities.css # 工具样式
│   ├── images/
│   └── fonts/
├── server/
│   ├── api/
│   │   ├── auth/         # 认证API
│   │   ├── users/        # 用户API
│   │   └── admin/        # 管理API
│   ├── middleware/       # 服务端中间件
│   └── utils/            # 服务端工具
├── types/
│   ├── api.ts            # API类型定义
│   ├── auth.ts           # 认证类型定义
│   └── global.ts         # 全局类型定义
├── tests/                # 测试文件
├── docs/                 # 项目文档
└── scripts/              # 构建脚本

开发服务器启动

1. 开发服务器启动

基本启动

环境变量配置

# 启动开发服务器
pnpm dev

# 指定端口
pnpm dev --port 3001

# 指定主机
pnpm dev --host 0.0.0.0

# 开启 HTTPS
pnpm dev --https

# 详细输出
pnpm dev --verbose

2. 基本配置文件

nuxt.config.ts 企业级配置:

// nuxt.config.ts
export default defineNuxtConfig({
  // 应用配置
  app: {
    head: {
      charset: 'utf-8',
      viewport: 'width=device-width, initial-scale=1',
      title: 'My Nuxt4 App',
      meta: [
        { name: 'description', content: 'My awesome Nuxt 4 application' }
      ]
    }
  },

  // 开发工具
  devtools: { 
    enabled: true,
    timeline: {
      enabled: true
    }
  },

  // TypeScript 配置
  typescript: {
    typeCheck: true,
    strict: true
  },

  // CSS 配置
  css: [
    '~/assets/css/main.css'
  ],

  // 模块配置
  modules: [
    '@nuxt/eslint',
    '@nuxt/test-utils',
    '@pinia/nuxt',
    '@vueuse/nuxt',
    '@nuxtjs/tailwindcss'
  ],

  // 运行时配置
  runtimeConfig: {
    // 服务端私有配置
    secretKey: process.env.NUXT_SECRET_KEY,
    
    // 客户端公共配置
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE || '/api'
    }
  },

  // 路由配置
  routeRules: {
    // 静态页面
    '/': { prerender: true },
    '/about': { prerender: true },
    
    // 动态页面
    '/dashboard/**': { ssr: false },
    '/admin/**': { 
      ssr: false,
      index: false // 禁止搜索引擎索引
    },
    
    // API 路由
    '/api/**': { 
      cors: true,
      headers: {
        'Access-Control-Allow-Origin': '*'
      }
    }
  },

  // 构建配置
  build: {
    analyze: process.env.NODE_ENV === 'production'
  },

  // 开发服务器配置
  devServer: {
    port: 3000,
    host: '0.0.0.0'
  }
});

3. 包管理配置

package.json 脚本配置:

{
  "name": "my-nuxt4-app",
  "private": true,
  "scripts": {
    "dev": "nuxt dev",
    "build": "nuxt build",
    "preview": "nuxt preview",
    "postinstall": "nuxt prepare",
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "test": "vitest",
    "test:coverage": "vitest --coverage",
    "type-check": "vue-tsc --noEmit"
  },
  "devDependencies": {
    "@nuxt/eslint": "^0.2.0",
    "@nuxt/test-utils": "^3.9.0",
    "@nuxtjs/tailwindcss": "^6.8.4",
    "@pinia/nuxt": "^0.5.1",
    "@vueuse/nuxt": "^10.5.0",
    "nuxt": "^3.8.0",
    "vitest": "^1.0.0",
    "vue-tsc": "^1.8.25"
  }
}

4. 开发环境验证

创建一个简单的测试页面来验证环境：

app/pages/index.vue

app/pages/about.vue

<template>
  <div class="container mx-auto p-8">
    <h1 class="text-4xl font-bold text-center mb-8">
      🚀 Nuxt4 项目搭建成功！
    </h1>
    
    <div class="grid grid-cols-1 md:grid-cols-2 gap-6">
      <div class="bg-white p-6 rounded-lg shadow-md">
        <h2 class="text-2xl font-semibold mb-4">
          环境信息
        </h2>
        <ul class="space-y-2">
          <li><strong>Node.js:</strong> {{ nodeVersion }}</li>
          <li><strong>Nuxt:</strong> {{ nuxtVersion }}</li>
          <li><strong>Vue:</strong> {{ vueVersion }}</li>
          <li><strong>当前时间:</strong> {{ currentTime }}</li>
        </ul>
      </div>
      
      <div class="bg-white p-6 rounded-lg shadow-md">
        <h2 class="text-2xl font-semibold mb-4">
          功能测试
        </h2>
        <div class="space-y-4">
          <div>
            <label class="block text-sm font-medium mb-2">
              计数器测试
            </label>
            <div class="flex items-center space-x-2">
              <button 
                @click="decrement"
                class="px-3 py-1 bg-red-500 text-white rounded"
              >
                -
              </button>
              <span class="px-4 py-1 bg-gray-100 rounded">
                {{ count }}
              </span>
              <button 
                @click="increment"
                class="px-3 py-1 bg-green-500 text-white rounded"
              >
                +
              </button>
            </div>
          </div>
          
          <div>
            <NuxtLink 
              to="/about" 
              class="inline-block px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
            >
              测试路由导航
            </NuxtLink>
          </div>
        </div>
      </div>
    </div>
  </div>
</template>

<script setup>
// 页面元数据
definePageMeta({
  title: 'Nuxt4 项目首页',
  description: '欢迎使用 Nuxt4 项目'
});

// 响应式数据
const count = ref(0);
const currentTime = ref('');

// 方法
const increment = () => count.value++;
const decrement = () => count.value--;

// 计算属性
const nodeVersion = computed(() => process.version);
const nuxtVersion = computed(() => '4.0.0');
const vueVersion = computed(() => '3.3.0');

// 生命周期
onMounted(() => {
  currentTime.value = new Date().toLocaleString();
});
</script>

代码规范配置

ESLint 配置步骤

1. 安装依赖

安装 ESLint

# 安装 ESLint 及相关依赖
pnpm add -D eslint @nuxt/eslint-config

# 安装 TypeScript ESLint 插件
pnpm add -D @typescript-eslint/parser @typescript-eslint/eslint-plugin

2. 配置文件说明

ESLint 配置主要包含以下几个方面:

基础配置

解析器配置
环境配置
扩展配置
全局变量

规则配置

Vue 规则
TypeScript 规则
代码风格规则
最佳实践规则

插件配置

Vue 插件
TypeScript 插件
Promise 插件
Import 插件

忽略配置

忽略文件
忽略规则
忽略路径
特殊注释

3. 配置作用说明

配置项	作用	示例
`parser`	指定代码解析器	`'vue-eslint-parser'`
`extends`	继承配置	`'@nuxt/eslint-config'`
`plugins`	启用插件	`['@typescript-eslint']`
`rules`	具体规则配置	`'no-console': 'warn'`

ESLint 配置可以根据项目需求进行调整,建议遵循团队统一的代码规范标准。

基础配置

完整配置

安装依赖

// eslint.config.js
import { createConfigForNuxt } from '@nuxt/eslint-config/flat'

export default createConfigForNuxt({
  // 基础配置
  rules: {
    // Vue 规则
    'vue/multi-word-component-names': 'off',
    'vue/no-multiple-template-root': 'off',
    'vue/attribute-hyphenation': ['error', 'always'],
    'vue/v-on-event-hyphenation': ['error', 'always'],
    
    // TypeScript 规则
    '@typescript-eslint/no-unused-vars': 'warn',
    '@typescript-eslint/no-explicit-any': 'warn',
    '@typescript-eslint/ban-ts-comment': 'off',
    
    // 通用规则
    'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off'
  }
})

Prettier 配置步骤

安装 Prettier 相关依赖：
pnpm add -D prettier eslint-plugin-prettier eslint-config-prettier
配置 ESLint 集成：在 .eslintrc.js 中添加 Prettier 插件和配置：
module.exports = { extends: [ // 其他配置 'plugin:prettier/recommended' // 必须放在最后 ], plugins: ['prettier'], rules: { 'prettier/prettier': 'error' // 将 Prettier 规则作为 ESLint 错误 } }
创建 Prettier 配置文件：在项目根目录创建 .prettierrc 文件，配置格式化规则。
配置编辑器：
- 在 VSCode 中安装 Prettier 插件
- 设置 "editor.formatOnSave": true
- 设置默认格式化工具为 Prettier

配置说明

eslint-plugin-prettier：将 Prettier 作为 ESLint 规则运行
eslint-config-prettier：禁用与 Prettier 冲突的 ESLint 规则
plugin:prettier/recommended：启用推荐的 Prettier 配置
prettier/prettier: 'error'：将 Prettier 格式化问题作为 ESLint 错误

Prettier 配置:

Prettier 配置

完整配置

安装依赖

// .prettierrc
{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5", 
  "printWidth": 80,
  "bracketSpacing": true,
  "arrowParens": "avoid",
  "endOfLine": "lf",
  "htmlWhitespaceSensitivity": "css",
  "insertPragma": false,
  "bracketSameLine": false,
  "jsxSingleQuote": false,
  "proseWrap": "preserve",
  "quoteProps": "as-needed",
  "requirePragma": false,
  "useTabs": false,
  "vueIndentScriptAndStyle": false
}

Husky + CommitLint 配置

为了规范代码提交流程,我们需要配置 Husky 和 CommitLint。

1. 安装依赖

安装 Husky

安装 CommitLint

# 安装 husky 和 lint-staged
pnpm add -D husky lint-staged

# 初始化 husky
pnpm dlx husky-init && pnpm install

# 创建 git hooks
pnpm husky install

2. 配置文件

commitlint.config.js

.lintstagedrc.js

package.json scripts

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat',     // 新功能
        'fix',      // Bug修复
        'docs',     // 文档更新
        'style',    // 代码格式(不影响代码运行的变动)
        'refactor', // 重构(既不是增加feature，也不是修复bug)
        'perf',     // 性能优化
        'test',     // 增加测试
        'chore',    // 构建过程或辅助工具的变动
        'revert',   // 回退
        'build',    // 打包
        'ci'        // CI相关变更
      ]
    ],
    'type-case': [2, 'always', 'lower-case'],     // type必须小写
    'type-empty': [2, 'never'],                   // type不能为空
    'scope-empty': [0],                           // scope可以为空
    'subject-empty': [2, 'never'],                // subject不能为空
    'subject-full-stop': [2, 'never', '.'],       // subject结尾不加'.'
    'header-max-length': [2, 'always', 72]        // header最长72字符
  }
};

3. Git Hooks 配置

.husky/pre-commit

.husky/commit-msg

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

pnpm lint-staged

提交规范说明:

feat: 新功能
fix: Bug修复
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
perf: 性能优化
test: 测试相关
chore: 构建/工具相关
revert: 代码回退

最佳实践

执行顺序：先运行 ESLint 再运行 Prettier
Git Hooks：建议在 pre-commit 钩子中自动格式化代码
团队统一：确保团队成员使用相同的 Prettier 配置
IDE 配置：建议在项目根目录添加 .vscode/settings.json 来统一编辑器配置

编辑此页面

什么是 Nuxt

介绍 Nuxt 框架特性、核心概念、发展历史及应用场景，了解 Nuxt 框架开发过程

目录结构与配置详解

理解Nuxt.js的目录结构与约定规范，掌握企业级应用的项目组织最佳实践

Nuxt4 项目搭建

推荐版本

最低要求

Vue Language Features (Volar)

TypeScript Vue Plugin

Tailwind CSS IntelliSense

ESLint

Prettier

GitLens

Markdown All in One

Docker

Thunder Client

Jest Runner

基础配置

规则配置

插件配置

忽略配置