安装与基本配置
约 1606 字大约 5 分钟
2026-01-25
创建 Nuxt 项目
使用官方的脚手架即可创建一个 Nuxt 项目
pnpm create nuxt@latest <project-name>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、纯函数工具
export interface UserProfile {
id: number
nickname: string
}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 下的内容
export default defineNuxtConfig({
runtimeConfig: {
apiSecret: 'aabbcc', // 仅服务端
public: {
baseURL: 'https://api.example.com',
},
},
})<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
export default defineAppConfig({
theme: 'light',
})<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_前缀:写入runtimeConfigNUXT_PUBLIC_前缀:写入runtimeConfig.public
app 配置
这里的 app 指的是 nuxt.config.ts 中的 app 配置,最常用的是 app.head,用于配置全局静态的头部信息(title / meta / link / script / style 等)
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 的页面
