nuxt.config.ts 是 Nuxt 3（或 Nuxt Bridge）项目中的核心配置文件，用于定义项目的构建、运行时行为、模块、插件、路由、SEO、服务器中间件等。以下是一份全面的 nuxt.config.ts 配置说明与常用功能示例。
📁 基础结构
// nuxt.config.ts
import { defineNuxtConfig } from 'nuxt/config'
export default defineNuxtConfig({
// 配置项
})🔧 主要配置项详解与示例
1. App 相关配置
app: {
head: {
title: 'My Nuxt App',
meta: [
{ charset: 'utf-8' },
{ name: 'viewport', content: 'width=device-width, initial-scale=1' },
{ hid: 'description', name: 'description', content: 'Nuxt 3 app' }
],
link: [
{ rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' }
]
}
}✅ 用于设置默认页面 <head> 内容（SEO、图标、视口等）。
2. 构建与开发服务器
devtools: { enabled: true }, // 启用 DevTools（如 Vue DevTools）
devServer: {
port: 3001,
host: '0.0.0.0'
},
build: {
transpile: ['some-esm-only-package'] // 强制 Babel 转译某些包
}3. 模块（Modules）集成
Nuxt 使用模块扩展功能（类似插件但更强大）：
modules: [
'@nuxtjs/tailwindcss',
'@pinia/nuxt',
'@nuxtjs/i18n',
'@nuxt/image',
'@nuxtjs/strapi',
// 或自定义本地模块
'./modules/my-custom-module'
]✅ 推荐使用官方或社区维护的模块，避免重复造轮子。
4. 插件（Plugins）
在应用启动时运行的逻辑（如初始化库、全局组件等）：
plugins: [
'~/plugins/axios',
'~/plugins/vue-gtag.client.ts', // .client 表示仅客户端执行
'~/plugins/pinia-persistence.server.ts' // .server 表示仅服务端执行
]示例插件 ~/plugins/axios.ts：
import { defineNuxtPlugin } from '#app'
import axios from 'axios'
export default defineNuxtPlugin(() => {
const api = axios.create({ baseURL: 'https://api.example.com' })
return {
provide: {
axios: api
}
}
})使用：const { $axios } = useNuxtApp()
5. 路由（Pages & Router）
Nuxt 默认基于文件系统的路由（pages/ 目录），但可自定义：
pages: true, // 启用 pages 路由（默认 true）
router: {
options: {
strict: false,
trailingSlash: false
}
}如需完全自定义路由，可关闭 pages: false 并手动配置 Vue Router。
6. CSS 与样式
css: [
'~/assets/css/main.css',
'@fortawesome/fontawesome-svg-core/styles.css'
]所有 CSS 文件会在全局注入。
7. 构建优化
vite: {
css: {
preprocessorOptions: {
scss: {
additionalData: '@use "~/assets/scss/_variables.scss" as *;'
}
}
}
},
nitro: {
// 服务端构建配置（用于 SSR / SSG）
preset: 'node-server', // 部署目标（vercel, netlify, node-server 等）
devProxy: {
'/api': { target: 'http://localhost:8000', changeOrigin: true }
}
}Nitro 是 Nuxt 3 的底层服务引擎，负责 SSR/SSG/API 路由等。
8. 环境变量与运行时配置
runtimeConfig: {
// 私有，仅服务端可用（不会暴露给客户端）
apiSecret: process.env.API_SECRET,
// 公共，会暴露给客户端
public: {
apiBase: process.env.NUXT_PUBLIC_API_BASE || '/api'
}
}使用方式：
💡 .env 文件中：
9. TypeScript 支持
Nuxt 3 原生支持 TS，无需额外配置。但可扩展类型：
typescript: {
strict: true,
shim: false, // 禁用自动生成 *.vue.d.ts
tsConfig: {
compilerOptions: {
baseUrl: '.',
paths: {
'@/*': ['./*']
}
}
}
}10. SSR / SSG 控制
ssr: true, // 默认开启服务端渲染
// 若做静态站点生成（SSG）
nitro: {
prerender: {
routes: ['/','/about','/blog']
}
}构建命令：
11. 图像优化（@nuxt/image）
安装后配置：
image: {
domains: ['images.unsplash.com', 'cdn.myshop.com'],
screens: {
xs: 320,
sm: 640,
md: 768,
lg: 1024,
xl: 1280
}
}使用：<NuxtImg src="/photo.jpg" width="300" format="webp" />
12. 国际化（@nuxtjs/i18n）
i18n: {
vueI18n: './i18n.config.ts',
locales: [
{ code: 'en', iso: 'en-US', file: 'en.json' },
{ code: 'zh', iso: 'zh-CN', file: 'zh.json' }
],
defaultLocale: 'en',
langDir: 'locales/'
}🧩 完整示例 nuxt.config.ts
import { defineNuxtConfig } from 'nuxt/config'
export default defineNuxtConfig({
// App metadata
app: {
head: {
title: 'My Awesome Nuxt App',
meta: [
{ name: 'description', content: 'Built with Nuxt 3' }
],
link: [{ rel: 'icon', href: '/favicon.svg' }]
}
},
// Modules
modules: [
'@nuxtjs/tailwindcss',
'@pinia/nuxt',
'@nuxt/image',
'@nuxtjs/i18n'
],
// Plugins
plugins: [
'~/plugins/axios'
],
// Runtime config
runtimeConfig: {
apiSecret: '',
public: {
apiBase: '/api'
}
},
// CSS
css: ['~/assets/css/main.css'],
// Vite
vite: {
css: {
preprocessorOptions: {
scss: {
additionalData: '@use "~/assets/scss/variables.scss" as *;'
}
}
}
},
// Nitro (server engine)
nitro: {
devProxy: {
'/api': { target: 'http://localhost:8000', changeOrigin: true }
}
},
// Image module
image: {
domains: ['example.com']
},
// i18n
i18n: {
locales: ['en', 'zh'],
defaultLocale: 'en'
},
// Build
build: {
transpile: ['trpc-nuxt']
}
})📚 参考文档
- Nuxt 3 官方文档
- Nuxt 模块目录
- Nitro 文档
如需特定功能（如 Auth、CMS 集成、PWA、SEO 优化等）的详细配置，请告知具体场景，我可以提供针对性示例。