Article

Nuxt实战(1)-项目初始化与配置

更新于：2025-04-26

原文链接-https://zhuanlan.zhihu.com/p/1936437051676426732

🚀 什么是 Nuxt

Nuxt 是一个建立在 Vue.js 上的服务器端渲染框架。它抽象出了管理异步数据、中间件和路由所涉及的大部分复杂配置。它还有助于使用行业标准架构来构造 Vue.js 应用程序，以构建简单或企业级的 Vue.js 应用程序。

✨ Nuxt4 的优点

基于 Vue3 的优势

性能优化-Nuxt4 充分利用了 Vue3 的所有优点，包括性能优化、响应式编程和更好的 TypeScript 支持
Composition API-Vue3 的 Composition API 使得代码更加灵活和可复用，为大型项目提供了更好的组织和管理方式

核心特性

服务端渲染（SSR）和静态站点生成（SSG）-解决单页应用（SPA）中的 SEO 问题，提高页面加载速度，改善用户体验
模块化生态系统-丰富的模块化生态系统，轻松扩展应用功能，减少开发工作量
文件系统路由-通过简单的文件和目录结构来组织应用路由，减少配置工作量
开箱即用-提供状态管理、中间件、页面过渡动画等功能，快速构建功能完善的应用
性能优化-使用最新的 Web 技术和优化技巧，提供更好的性能和更快的加载速度
灵活配置-提供灵活的配置选项和插件系统，满足各种复杂的开发需求

📋 环境要求

Node.js-确保使用偶数版本号
Nuxtr-安装社区开发的 Nuxtr 扩展
Volar-启用接管模式（TakeOver Mode）或添加 TypeScript Vue 插件

🛠️ 项目安装

创建新项目

pnpm dlx nuxi@latest init <project-name>

打开项目文件夹
Terminal window
```
code <project-name>
```

安装依赖项

# 在运行 pnpm install 之前，确保你在 `.npmrc` 中有 `shamefully-hoist=true`
pnpm install

启动开发服务器
Terminal window
```
pnpm dev -o
```

完成后，浏览器会自动打开 http://localhost:3000

📁 目录结构

project/
├── .nuxt/          # Nuxt 开发时生成的 Vue 应用程序
├── .output/        # 生产构建输出目录
├── assets/         # 构建工具处理的网站资产
├── components/     # Vue 组件目录
├── composables/    # Vue 组合式函数自动导入
├── content/        # 基于文件的内容管理系统（CMS）
├── layouts/        # 布局框架，提取可重用的 UI 模式
├── middleware/     # 路由导航前运行的中间件
├── modules/        # 本地模块自动注册
├── node_modules/   # 项目依赖存储目录
├── pages/          # 基于文件的路由功能
├── plugins/        # Vue 插件和其他功能
├── public/         # 静态资源目录
├── server/         # API 和服务器处理程序
├── utils/          # 工具函数自动导入
├── .env            # 环境变量配置
├── .gitignore      # Git 忽略文件配置
├── .nuxtignore     # Nuxt 构建时忽略的文件
├── app.vue         # Nuxt 应用主组件（入口文件）
├── app.config.ts   # 应用响应式配置
├── nuxt.config.ts  # Nuxt 配置文件
├── package.json    # 项目依赖和脚本
└── tsconfig.json   # TypeScript 配置

📝 总结

后续开发会以 Nuxt 为核心，开发一个类似网址导航的页面，探索 Nuxt 的各种特性和功能。我会在此基础上加入自己的设计和想法，致力于提高用户体验。

🔧 配置项目开发规范

💡 为什么要做项目规范

核心价值

提高代码质量-确保代码的一致性和可读性，使团队成员能够更容易地理解和维护代码，减少错误和缺陷
加强团队协作-统一的开发规范让团队成员高效协作，减少沟通成本和误解，加快项目进度
降低维护成本-建立清晰的代码结构和文档，使软件系统的维护和升级更加容易
提升软件可靠性-减少代码中的潜在问题，提高软件的稳定性和可靠性
促进项目管理-明确的任务划分、版本控制和文档要求，帮助更好地管理项目进度和资源

🛠️ 工具介绍

工具	功能描述
ESLint	静态代码分析工具，检查语法问题、编码风格和潜在问题
Prettier	代码格式化工具，统一团队代码格式
Stylelint	CSS 代码检测工具，规避 CSS 错误和统一风格
Husky	Git Hook 工具，在提交或推送时自动运行检测
Lint-staged	对 Git 暂存区代码进行检测，确保代码质量
Commitlint	规范 commit 提交信息格式

📝 配置 ESLint

1. 安装依赖

pnpm add -D eslint @nuxt/eslint-config

2. 配置 `.eslintrc.cjs`

module.exports = {
  root: true,
  env: {
    browser: true, // 支持浏览器环境的检测
    es2021: true,  // 支持 ES2021 语法的检测
    node: true     // 支持 Node 环境的检测
  },
  extends: ['@nuxt/eslint-config'],
  overrides: [],
  parserOptions: {
    ecmaVersion: 'latest', // 使用最新的 ECMAScript 版本
    sourceType: 'module'   // 文件是 ES6 模块规范
  },
  plugins: ['vue'],
  rules: {
    'camelcase': 2,                    // 驼峰命名
    'indent': [2, 2],                  // 缩进 2 个空格
    'semi': [2, 'never'],              // 禁用行尾分号
    'quotes': ['error', 'single'],     // 强制使用单引号
    'no-debugger': 2,                  // 不能使用 debugger
    'no-empty': 2,                     // 块语句中的内容不能为空
    'no-extra-parens': 2,              // 禁止非必要的括号
    'no-extra-semi': 2,                // 禁止多余的分号
    'comma-dangle': [2, 'never'],      // 键值对最后一个不能有逗号
    'spaced-comment': ['error', 'always'] // 注释必须有空格
  }
}

3. VS Code 配置

在 VS Code 设置中添加-

{
  "editor.codeActionsOnSave": {
    "source.fixAll": false,
    "source.fixAll.eslint": true
  }
}

注意-由于 ESLint 已经配置了代码格式化，所以没有必要使用 Prettier 来重复这个功能。

🎨 配置 Stylelint

1. 安装依赖

pnpm add stylelint @nuxtjs/stylelint-module stylelint-config-standard stylelint-order stylelint-config-recommended-vue -D

2. 配置 `nuxt.config.ts`

export default defineNuxtConfig({
  modules: [
    '@nuxtjs/stylelint-module'
  ]
})

3. 新增 `.stylelintrc.cjs`

module.exports = {
  extends: [
    'stylelint-config-standard',
    'stylelint-config-recommended-vue' // 确保放在最后
  ],
  plugins: ['stylelint-order'],
  rules: {
    'color-hex-case': 'upper',           // 颜色指定大写
    'block-no-empty': true,              // 禁止空块
    'color-hex-length': 'long',          // 颜色 6 位长度
    'selector-type-no-unknown': [true, {
      ignoreTypes: []
    }],
    'selector-pseudo-element-no-unknown': [true, {
      ignorePseudoElements: ['v-deep']
    }],
    'no-descending-specificity': null,
    'at-rule-no-unknown': null,
    'comment-no-empty': true,
    'shorthand-property-no-redundant-values': true,
    'value-no-vendor-prefix': true,
    'property-no-vendor-prefix': true,
    'number-leading-zero': 'never',
    'no-empty-first-line': true,
    // CSS 属性排序
    'order/properties-order': [
      'position', 'top', 'right', 'bottom', 'left', 'z-index',
      'display', 'justify-content', 'align-items',
      'float', 'clear', 'overflow', 'overflow-x', 'overflow-y',
      'margin', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
      'border', 'border-style', 'border-width', 'border-color',
      'border-radius', 'padding', 'padding-top', 'padding-right',
      'padding-bottom', 'padding-left', 'width', 'min-width', 'max-width',
      'height', 'min-height', 'max-height', 'font-size', 'font-family',
      'font-weight', 'text-align', 'text-justify', 'text-indent',
      'text-overflow', 'text-decoration', 'white-space', 'color',
      'background', 'background-position', 'background-repeat',
      'background-size', 'background-color', 'background-clip',
      'opacity', 'filter', 'list-style', 'outline', 'visibility',
      'box-shadow', 'text-shadow', 'resize', 'transition'
    ]
  }
}

4. 添加脚本命令

{
  "scripts": {
    "lint:style": "stylelint src/**/*.{css,less,vue} --fix"
  }
}

🐕 配置 Husky

1. 安装依赖

pnpm add husky -D

2. 初始化

pnpm exec husky init

完成后会在根目录生成 .husky 文件夹。

🎯 配置 Lint-staged

1. 安装依赖

pnpm add lint-staged -D

2. 添加脚本命令

{
  "scripts": {
    "pre-commit": "lint-staged"
  }
}

3. 配置 `.lintstagedrc`

{
  "lint-staged": {
    "*.{js,jsx,vue,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ]
  }
}

4. 修改 `.husky/pre-commit`

npm run pre-commit

📋 配置 Commitlint

1. 安装依赖

pnpm add @commitlint/config-conventional @commitlint/cli -D

2. 创建 `commitlint.config.cjs`

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'build',    // 编译相关的修改
      'feat',     // 新功能
      'fix',      // 修补 bug
      'docs',     // 文档修改
      'style',    // 代码格式修改
      'refactor', // 重构
      'perf',     // 性能优化
      'test',     // 测试用例修改
      'revert',   // 代码回滚
      'ci',       // 持续集成修改
      'config',   // 配置修改
      'chore'     // 其他改动
    ]],
    'type-empty': [2, 'never'],        // type 不能为空
    'type-case': [0, 'always', 'lower-case'],
    'scope-empty': [0],
    'scope-case': [0],
    'subject-empty': [2, 'never'],     // subject 不能为空
    'subject-case': [0],
    'subject-full-stop': [0, 'never', '.'],
    'header-max-length': [2, 'always', 72], // header 最长 72 字符
    'body-leading-blank': [0],
    'footer-leading-blank': [0, 'always']
  }
}

3. 添加脚本命令

{
  "scripts": {
    "commitlint": "commitlint --config commitlint.config.cjs -e -V"
  }
}

4. 创建 `.husky/commit-msg`

npx husky add .husky/commit-msg

添加内容-

npm run commitlint

配置完成后，每次提交 commit 时都会检查提交信息是否符合规范。

📦 使用 release-it 自动管理版本号和生成 CHANGELOG

🎯 release-it

✅ 版本管理-自动增加版本号并提交到 Git
📝 变更日志-生成 Changelog 并提交到 Git
🏷️ Git 标签-创建 Git 标签并推送到远程仓库
📦 包发布-发布到 npm 等软件仓库
🚀 发行版-在 GitHub、GitLab 等平台创建发行版

🛠️ 安装配置

1. 安装依赖

pnpm add release-it @release-it/conventional-changelog -D

2. 创建 `.release-it.json` 配置文件

{
  "plugins": {
    "@release-it/conventional-changelog": {
      "preset": {
        "name": "conventionalcommits",
        "types": [
          { "type": "feat", "section": "✨ Features | 新功能" },
          { "type": "fix", "section": "🐛 Bug Fixes | Bug 修复" },
          { "type": "chore", "section": "🔧 Chores | 其他更新" },
          { "type": "docs", "section": "📚 Documentation | 文档" },
          { "type": "style", "section": "💄 Styles | 风格" },
          { "type": "refactor", "section": "♻️ Code Refactoring | 代码重构" },
          { "type": "perf", "section": "⚡ Performance Improvements | 性能优化" },
          { "type": "test", "section": "✅ Tests | 测试" },
          { "type": "revert", "section": "⏪ Reverts | 回退" },
          { "type": "build", "section": "🏗️ Build System | 构建" },
          { "type": "ci", "section": "👷 Continuous Integration | CI 配置" },
          { "type": "config", "section": "🔧 CONFIG | 配置" }
        ]
      },
      "infile": "CHANGELOG.md",
      "ignoreRecommendedBump": true,
      "strictSemVer": true
    }
  },
  "git": {
    "commitMessage": "chore: Release v${version}"
  },
  "github": {
    "release": true,
    "draft": false
  }
}

3. 添加脚本命令

{
  "scripts": {
    "release": "release-it"
  }
}

🚀 使用方式

# 默认更新次版本号
pnpm release

# 更新主版本号 (1.0.0 -> 2.0.0)
pnpm release major

# 更新次版本号 (1.0.0 -> 1.1.0)
pnpm release minor

# 更新修订号 (1.0.0 -> 1.0.1)
pnpm release patch

执行 pnpm release 命令后，工具会自动-

📈 更新版本号
📝 生成 CHANGELOG
🏷️ 创建 Git 标签
🚀 推送到远程仓库
📦 创建 GitHub Release

🎨 安装 Nuxt UI、TailwindCSS 和配置 TypeScript

💭 为什么选择 Nuxt UI？

相比 Ant Design Vue、Element-Plus 等传统组件库，Nuxt UI 具有以下优势-

🎯 官方推荐-Nuxt 官方推荐的 UI 组件库
🔧 完美兼容-与 Nuxt 完美集成，开箱即用
📘 TypeScript 支持-完全用 TypeScript 编写，提供完整类型支持
🎨 现代设计-更符合年轻化、现代化的设计风格
⚡ 性能优化-基于 Headless UI 和 Tailwind CSS

官方文档-https://ui.nuxt.com/

🛠️ 安装 Nuxt UI

1. 安装依赖

pnpm add @nuxt/ui

2. 配置 `nuxt.config.ts`

export default defineNuxtConfig({
  modules: ['@nuxt/ui']
})

3. 使用示例

在 app.vue 中添加代码-

<template>
  <div class="w-screen h-screen flex justify-around items-center">
    <UButton>Button</UButton>
    <UBreadcrumb :links="links" />
    <Icon
      name="uil:github"
      size="48"
    />
  </div>
</template>

<script setup lang="ts">
const links = [
  {
    label: '首页',
    icon: 'i-heroicons-home'
  },
  {
    label: '导航',
    icon: 'i-heroicons-nav'
  }
]
</script>

4. 安装图标库（可选）

如果遇到图标相关错误，需要安装对应的图标库-

pnpm add @iconify-json/heroicons

📘 配置 TypeScript

1. 安装依赖

pnpm add -D vue-tsc@^1 typescript

2. 配置 `nuxt.config.ts`

export default defineNuxtConfig({
  // 构建时启动类型检查
  typescript: {
    typeCheck: true
  }
})

🎉 总结

至此，项目的基础配置已经完成！现在你可以-

✅ 使用 Nuxt UI 的所有组件
✅ 享受 TailwindCSS 的便利
✅ 获得完整的 TypeScript 支持
✅ 拥有规范的代码提交流程
✅ 自动化的版本管理

接下来就可以开始开发页面布局和具体功能了！

Nuxt实战(1)-项目初始化与配置

🚀 什么是 Nuxt

✨ Nuxt4 的优点

基于 Vue3 的优势

核心特性

📋 环境要求

🛠️ 项目安装

📁 目录结构

📝 总结

🔧 配置项目开发规范

💡 为什么要做项目规范

核心价值

🛠️ 工具介绍

📝 配置 ESLint

1. 安装依赖

2. 配置 .eslintrc.cjs

3. VS Code 配置

🎨 配置 Stylelint

1. 安装依赖

2. 配置 nuxt.config.ts

3. 新增 .stylelintrc.cjs

4. 添加脚本命令

🐕 配置 Husky

1. 安装依赖

2. 初始化

🎯 配置 Lint-staged

1. 安装依赖

2. 添加脚本命令

3. 配置 .lintstagedrc

4. 修改 .husky/pre-commit

📋 配置 Commitlint

1. 安装依赖

2. 创建 commitlint.config.cjs

3. 添加脚本命令

4. 创建 .husky/commit-msg

📦 使用 release-it 自动管理版本号和生成 CHANGELOG

🎯 release-it

🛠️ 安装配置

1. 安装依赖

2. 创建 .release-it.json 配置文件

3. 添加脚本命令

🚀 使用方式

🎨 安装 Nuxt UI、TailwindCSS 和配置 TypeScript

💭 为什么选择 Nuxt UI？

🛠️ 安装 Nuxt UI

1. 安装依赖

2. 配置 nuxt.config.ts

3. 使用示例

4. 安装图标库（可选）

📘 配置 TypeScript

1. 安装依赖

2. 配置 nuxt.config.ts

🎉 总结

2. 配置 `.eslintrc.cjs`

2. 配置 `nuxt.config.ts`

3. 新增 `.stylelintrc.cjs`

3. 配置 `.lintstagedrc`

4. 修改 `.husky/pre-commit`

2. 创建 `commitlint.config.cjs`

4. 创建 `.husky/commit-msg`

2. 创建 `.release-it.json` 配置文件

2. 配置 `nuxt.config.ts`

2. 配置 `nuxt.config.ts`