2.2 nuxt.config.ts 配置详解

2.2 nuxt.config.ts 配置详解

承接 2.1 的目录骨架，本节讲行为开关：nuxt.config.ts 是全项目的规则中枢，渲染模式、模块加载、运行时参数都在这里声明。本节给出的配置分层思维与 runtimeConfig 的安全边界，会在第 6 章（服务端读取密钥）与第 9 章（多环境部署）被反复使用。

配置文件的解剖

一个中等规模项目的配置文件长这样（节选）：

// nuxt.config.ts
export default defineNuxtConfig({
  // 应用元信息
  app: {
    head: {
      title: '接力商城',
      htmlAttrs: { lang: 'zh-CN' },
      meta: [
        { name: 'viewport', content: 'width=device-width, initial-scale=1' },
      ],
    },
  },

  // 运行时配置：能被两端读到的动态值
  runtimeConfig: {
    apiSecret: '',            // 仅服务端可读（无 public 前缀）
    public: {
      apiBase: '/api',        // 服务端与浏览器都可见
    },
  },

  // 全局行为
  ssr: true,                  // 整站服务端渲染开关
  devtools: { enabled: true },

  // 模块与 CSS
  modules: ['@nuxtjs/tailwindcss'],
  css: ['~/assets/css/main.css'],

  // 构建相关
  nitro: {
    compressPublicAssets: true,
  },
})
​

读配置的心法是分层：应用信息（app）、运行时值（runtimeConfig）、全局行为（ssr/devtools）、生态接入（modules/css）、服务端细节（nitro）。遇到任何需求，先判断它属于哪一层，再查该层的选项——比全局乱搜快得多。

图 2-2：配置的作用域分层

runtimeConfig：一条安全红线

配置里最重要的安全概念藏在 runtimeConfig 的结构里：只有 public 子树会暴露给浏览器。

runtimeConfig: {
  dbPassword: 'server-only',   // 浏览器永远拿不到
  public: { apiBase: '/api' }, // 两端都可见
}
​

组件里用 useRuntimeConfig() 读取时，服务端执行能看到全部字段，客户端执行只能看到 public 部分。这带来一条硬规则：凡是密钥、内部端点、第三方私钥，一律放在 public 之外。

runtimeConfig 的另一半价值是环境覆盖。部署时不用改代码，环境变量自动注入：

# 生产环境用环境变量覆盖默认值
# 命名规则：NUXT_ 前缀 + 下划线连接层级
NUXT_PUBLIC_API_BASE=https://api.example.com
NUXT_DB_PASSWORD=real-secret-here

node .output/server/index.mjs
​

这套机制让"开发用本地库、测试用预发库、生产用正式库"的多环境管理（第 9 章展开）只需维护环境变量，配置文件保持一份。

app.head 与按页覆盖

全局 head 在配置里声明，页面级用 useHead 或 useSeoMeta 覆盖：

<script setup>
// 页面里动态设置标题与描述，覆盖全局默认值
useHead({
  title: '商品详情',
  meta: [
    { name: 'description', content: '机械键盘 Pro 的详细参数与价格' },
  ],
})
</script>
​

规则是就近覆盖：页面设置生效，未设置的项继承全局。第 8 章讲 SEO 时会把 useSeoMeta、Open Graph 与结构化数据一并展开，此处先记住入口在哪。

配置的优先级链条

同一件事可能在多处声明，优先级从低到高为：

1. nuxt.config.ts 全局默认（如 ssr: true）；
2. routeRules 按路由覆盖（如 /admin/** 关掉 SSR）；
3. 页面内 definePageMeta 再覆盖（单个页面的布局、中间件）。

// 全局开 SSR，后台路由关掉
routeRules: {
  '/admin/**': { ssr: false },
}
​

这条链条是 1.2"模式是属性"的实现基础——整站默认 + 路由例外 + 页面微调，三层粒度够覆盖绝大多数需求。

配置文件的团队协作规范

配置文件是全项目行为的单一来源，也最容易变成"人人敢改、无人敢删"的重灾区。三条协作规范值得从项目第一天就立起来：

规范一：配置变更走评审。nuxt.config 的每次修改都可能影响所有人（改个 ssr 开关、换个构建选项），把它当作架构变更对待——PR 里说明动机与影响面，而不是顺手一行提交。

规范二：注释写"为什么"。compressPublicAssets: true // 2024-03 为静态资源省 30% 体积，压测见内部 wiki 远比裸配置有价值。半年后没人记得这行为什么存在，删了它踩坑时，注释是唯一的线索。

规范三：定期瘦身。每个季度过一遍配置：实验特性开关（compatibility 标志）该摘的摘、废弃选项该删的删、被注释掉的旧配置直接清掉。升级大版本时的配置迁移成本，与配置文件的"考古层"厚度成正比。

环境变量管理是配置协作的另一半。推荐三级结构：项目里放 .env.example 列出所有需要的变量名与说明（不含真实值）；本地开发用 .env（进 gitignore）；CI 与生产环境的密钥托管在平台的密钥管理里。新人克隆项目后，照着 example 文件五分钟配好本地环境——这份体验的差异，就是"配置工程"成熟度的差异。

⚠️ 常见坑：把密钥写进 public 子树。曾有项目把对象存储的私钥放进 public 配置，等于把钥匙刻在了交付到每个浏览器的 JS 里。自查方法：打开生产构建的客户端产物，全局搜索该值，能搜到就是泄了。

💡 关键直觉：nuxt.config 管"这个项目长什么样、跑在哪"，runtimeConfig 管"这次跑的时候用什么参数"。前者编译进产物，后者部署时可变——分清这两者，多环境部署的思路自然清晰。

本节要点回顾

• 五层读法：app 外壳、runtimeConfig 运行值、行为开关、生态接入、nitro 服务端细节，按层定位选项；
• 安全红线：public 子树之外的 runtimeConfig 字段不会进浏览器，密钥一律放外面；
• 环境覆盖：NUXT_ 前缀环境变量在部署时覆盖默认值，配置文件保持单一来源；
• 就近覆盖链：全局默认 → routeRules → definePageMeta，粒度逐层变细；
• useHead 入口：页面级标题与 meta 在此覆盖全局，SEO 细节第 8 章展开。