安装与基本配置

约 1606 字大约 5 分钟

2026-01-25

创建 Nuxt 项目

使用官方的脚手架即可创建一个 Nuxt 项目

pnpm

pnpm create nuxt@latest <project-name>

bun

bun create nuxt@latest <project-name>

一个典型的 Nuxt 项目结构如下

hello-nuxt

app

assets 资源目录（参与打包处理，如 scss、图片）

components 组件目录（自动导入）

composables 组合式 API 目录（自动导入）

layouts 布局

middleware 路由中间件

pages 页面目录，基于文件结构自动生成路由

index.vue 项目首页

plugins 插件目录

app.vue 应用入口（通常简称 App.vue）

shared 跨端共享代码（如 types、schema、常量）

server

api 服务端 API（映射到 /api/*）

routes 自定义服务端路由

middleware 服务端中间件（每个请求都会经过）

plugins Nitro 插件（服务进程启动时注册）

layers 本地 Nuxt Layers（可复用基础层）

public 静态资源目录（原样输出）

app.config.ts 应用配置（defineAppConfig）

nuxt.config.ts Nuxt 框架配置（css、ssr、vite、app、modules 等）

pnpm-lock.yaml

package.json

README.md

tsconfig.json

package.json 中的命令

build: nuxt build: 生成生产构建产物
dev: nuxt dev: 启动开发服务，支持 HMR 与调试
generate: nuxt generate: 生成静态站点（SSG）产物
preview: nuxt preview: 本地预览生产构建或静态产物
postinstall: nuxt prepare: 生成类型与自动导入

其他目录

`shared`

适合放前后端都能复用的 纯 TypeScript 代码，比如类型定义、枚举常量、校验 schema、纯函数工具

shared/types/user.ts

export interface UserProfile {
  id: number
  nickname: string
}

app/pages/profile.vue

import type { UserProfile } from '~/shared/types/user'

笔记

shared 内尽量不要直接依赖 window、document 或 Node 专有 API，保持跨端可复用

`server`

用于放服务端逻辑

常见子目录有：

server/api/*：后端接口，默认映射到 /api/*
server/routes/*：自定义服务端路由（不走 /api 前缀）
server/middleware/*：请求级中间件（每个 HTTP 请求都会执行）
server/plugins/*：Nitro 运行时插件（服务进程启动时注册）

`layers`

用于复用一套 Nuxt 能力（页面、布局、组件、插件、配置等），适合多项目共享基础能力

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    './layers/base',
  ],
})

笔记

本地 layers/* 通常会被自动扫描；需要显式控制顺序或复用外部 layer 时，使用 extends 更清晰

应用入口

在 Nuxt 中 App.vue（即 app/app.vue）会被视为应用的根入口，默认情况下 Nuxt 会为每个路由渲染页面内容，App.vue 通常负责决定页面被包在什么结构里以及入口处要做哪些全局事情

常见用途

使用 NuxtLayout 定义页面布局或自定义布局骨架
使用 NuxtPage 定义路由占位以渲染页面
使用 beforeEach 监听全局路由事件（不推荐，示例用途）
编写全局样式或引入全局样式

如果创建了 app/app.vue，那么一定要保留 NuxtPage，否则页面不会渲染

<template>
  <NuxtLayout>
    <!-- 页面内容 -> vue-router -->
    <NuxtPage />
  </NuxtLayout>
</template>

<script lang="ts" setup>
const router = useRouter()

router.beforeEach((to, from) => {
  console.log('beforeEach', to, from)
})
</script>

信息

全局样式除了写在 app/app.vue，也可以通过 nuxt.config.ts 的 css 字段统一引入
全局路由守卫在 Nuxt 中更推荐用 app/middleware/*.global.ts，这样 SSR/CSR 逻辑更一致

框架配置

框架配置 nuxt.config.ts 位于项目根目录，用于配置框架能力，例如 css、vite、modules 等，具体可以参考: https://nuxt.com/docs/api/configuration/nuxt-config

运行时配置

运行时配置（runtimeConfig）主要用于 "运行时可变" 的配置，可以调用 useRuntimeConfig 来获取运行时信息

重要

服务端可以读取 runtimeConfig 中的全部字段；客户端只能读取 public 下的内容

nuxt.config.ts

export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: 'aabbcc', // 仅服务端
    public: {
      baseURL: 'https://api.example.com',
    },
  },
})

app.vue

<script lang="ts" setup>
const config = useRuntimeConfig()

if (process.server) {
  console.log('API secret:', config.apiSecret)  // apiSecret 仅在 server 端存在
}
</script>

应用配置

应用配置（appConfig）用于 "构建时确定" 的公共配置，例如主题、品牌色等，可以调用 useAppConfig 来获取应用配置信息

应用配置可以写在 nuxt.config.ts，也可以独立放在 app.config.ts

app.config.ts

export default defineAppConfig({
  theme: 'light',
})

app.vue

<script lang="ts" setup>
const appConfig = useAppConfig()
</script>

在 env 定义环境变量

Nuxt 会读取项目根目录的 .env 文件，因此可以把环境变量放在这些文件里。这些环境变量可按不同环境被拆分：.env、.env.local、.env.development、.env.production 等

笔记

.env 文件不会被打包进客户端代码，但 NUXT_PUBLIC_ 前缀的变量会暴露给浏览器，所以需要避免存放敏感信息

# .env
NUXT_API_SECRET=server_secret
NUXT_PUBLIC_BASE_URL=https://api.example.com

对应规则

NUXT_ 前缀：写入 runtimeConfig
NUXT_PUBLIC_ 前缀：写入 runtimeConfig.public

app 配置

这里的 app 指的是 nuxt.config.ts 中的 app 配置，最常用的是 app.head，用于配置全局静态的头部信息（title / meta / link / script / style 等）

nuxt.config.ts

export default defineNuxtConfig({
  app: {
    head: {
      charset: 'utf-8',
      viewport: 'width=device-width, initial-scale=1',
      title: 'My App',
      titleTemplate: '%s · My App',
      meta: [
        { name: 'description', content: 'A Nuxt site' },
        { name: 'keywords', content: 'Nuxt, Vue, SSR' },
      ],
      link: [
        { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' },
      ],
      script: [
        { src: 'https://example.com/analytics.js', body: true },
      ],
      style: [
        { children: 'body { color: #333; }' },
      ],
    },
  },
})

笔记

charset 建议使用 utf-8，避免编码问题
viewport 可按业务决定是否限制缩放
大段样式更推荐写在 assets 或通过 nuxt.config.ts 的 css 引入

`useHead`

需要动态或页面级别的 head 信息时，使用 useHead 更合适

<script lang="ts" setup>
const title = ref('文章详情')

useHead({
  title,
  meta: [
    { name: 'description', content: '文章内容简介' },
  ],
  bodyAttrs: {
    class: 'theme-light',
  },
})
</script>

模板内置组件

在模板中也可以直接使用 <Head> / <Title> / <Meta> 等组件，语义直观，写起来更像 HTML

<template>
  <Head>
    <Title>关于我们</Title>
    <Meta name="description" content="公司介绍与团队信息" />
  </Head>
</template>

重要

head 的配置优先级：模板内置组件 > useHead > app.head

SSR 配置

Nuxt 默认以 SSR 方式渲染页面，如果要全局切换为 SPA，可以在 nuxt.config.ts 中设置 ssr: false

混合渲染（Hybrid Rendering）

Nuxt 支持按路由维度混合使用 SSR / SSG / CSR，让不同页面采用不同渲染策略

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true },     // 首页走 SSG
    '/admin/**': { ssr: false },  // 管理后台走 CSR
    '/blog/**': { isr: 60 },      // 文章页启用 ISR（秒）
  },
})

笔记

prerender 适合内容稳定的页面（营销页、文档页）
ssr: false 适合强交互、依赖浏览器 API 的页面
isr 适合内容会更新，但无需每次都实时 SSR 的页面

补充篇

原理篇

工程化搭建

响应式

渲染器

渲染器的基础实现

基础篇

原理篇