app.config.ts
使用 App Config 文件在应用内暴露响应式配置。
Nuxt 提供了一个 app.config
配置文件,用于在应用内暴露响应式配置,支持在运行时通过生命周期函数或 Nuxt 插件更新配置,并支持热模块替换(HMR)进行编辑。
你可以使用 app.config.ts
文件轻松提供运行时应用配置。该文件可以使用 .ts
、.js
或 .mjs
扩展名。
app.config.ts
export default defineAppConfig({
foo: 'bar'
})
请不要在
app.config
文件中放入任何秘密值。它将被暴露到用户客户端包中。用法
要将配置和环境变量暴露给应用的其他部分,需要在 app.config
文件中定义配置。
app.config.ts
export default defineAppConfig({
theme: {
primaryColor: '#ababab'
}
})
现在,我们可以在服务器渲染页面时以及浏览器端统一访问 theme
,使用 useAppConfig
组合式函数。
pages/index.vue
<script setup lang="ts">
const appConfig = useAppConfig()
console.log(appConfig.theme)
</script>
可以使用 updateAppConfig
工具在运行时更新 app.config
。
pages/index.vue
<script setup>
const appConfig = useAppConfig() // { foo: 'bar' }
const newAppConfig = { foo: 'baz' }
updateAppConfig(newAppConfig)
console.log(appConfig) // { foo: 'baz' }
</script>
类型定义 App Config
Nuxt 会尝试自动从提供的应用配置生成 TypeScript 接口,这样你不必手动定义类型。
但有些情况下你想自己定义类型。可能想要定义两种类型。
App Config 输入类型
AppConfigInput
可能由模块作者使用,用于声明设置应用配置时有效的 输入 选项。这不会影响 useAppConfig()
的类型。
index.d.ts
declare module 'nuxt/schema' {
interface AppConfigInput {
/** 主题配置 */
theme?: {
/** 主应用颜色 */
primaryColor?: string
}
}
}
// 为了增强类型时总是确保导入或导出某个内容
export {}
App Config 输出类型
如果想为调用 useAppConfig()
的结果定义类型,则需要扩展 AppConfig
。
定义
AppConfig
类型时请谨慎,因为这会覆盖 Nuxt 根据你实际定义的应用配置推断出的类型。index.d.ts
declare module 'nuxt/schema' {
interface AppConfig {
// 这会完全替换已有的 `theme` 属性的推断类型
theme: {
// 你可能想为此值指定更具体的类型,比如字符串字面量类型
primaryColor?: 'red' | 'blue'
}
}
}
// 为了增强类型时总是确保导入或导出某个内容
export {}
合并策略
Nuxt 在应用的 层(layers) 中使用自定义的合并策略来处理 AppConfig
。
此策略使用 Function Merger 实现,允许为 app.config
中值为数组的每个键定义自定义合并策略。
函数合并器只能在扩展层(extended layers)中使用,不能用于项目中的主
app.config
。以下是用法示例:
export default defineAppConfig({
// 默认数组值
array: ['hello'],
})
export default defineAppConfig({
// 使用合并函数覆盖默认数组值
array: () => ['bonjour'],
})
已知限制
截至 Nuxt v3.3,app.config.ts
文件和 Nitro 共享,因此存在以下限制:
- 不能在
app.config.ts
中直接导入 Vue 组件。 - Nitro 上下文中,有些自动导入不可用。
这些限制是因为 Nitro 处理应用配置时不完整支持 Vue 组件。
虽然可以在 Nitro 配置中通过使用 Vite 插件作为变通方案,但不推荐这样做:
nuxt.config.ts
export default defineNuxtConfig({
nitro: {
vite: {
plugins: [vue()]
}
}
})
使用此变通方法可能会导致意外行为和错误。Vue 插件只是 Nitro 上下文中不可用的众多插件之一。
相关问题:
Nitro v3 将通过移除对应用配置的支持来解决这些限制。
你可以在 此拉取请求 中跟踪进展。