Nuxt 中的 `import.meta` 完全指南：客户端与服务端代码的静态环境判断与 tree-shaking

import.meta 是 ES 模块规范提供的元信息对象，在 Nuxt 中它被扩展为一组描述"当前代码运行在何处、以何种方式运行"的编译期标志位。利用 import.meta.client、import.meta.server、import.meta.dev 等属性，你可以写出真正被"静态注入、构建期替换"的环境判断代码，从而让打包器在产物中彻底剔除永远不会执行的无关分支（tree-shaking）。本篇基于 Nuxt 官方文档与仓库源码（packages/nuxt、packages/vite、packages/schema），系统讲解这些属性的语义、在 Nuxt 内部的真实使用方式，以及如何基于 import.meta.url 在模块中安全地解析文件路径。

import.meta 对象是什么

在使用 ES Modules 编写的代码中，可以通过 import.meta 获取当前被导入/编译模块的元信息。Nuxt 整个生态的源码与文档中都大量依赖它来区分代码在客户端（浏览器）还是服务端（Nitro）执行。

与普通的 process.env 读取不同，Nuxt 中这些 import.meta.* 标志是在构建时静态注入的常量：构建工具会在编译阶段直接把这些表达式替换为布尔字面量。这意味着 if (import.meta.server) { ... } 在被打包到客户端产物时会被常量折叠，未选中的分支连同其引用的模块都不会进入最终产物——这正是官方文档将其用于 runtime 代码 tree-shaking 的底层原理。

从类型层面看，Nuxt 通过全局接口扩展为 import.meta 补充了这些属性，类型声明位于 augments.ts，其中 browser、client、dev、envName、server、test 均为布尔/字符串属性。此外在 build-only.d.ts 中还在构建期扩展了 import.meta.hot、import.meta.webpackHot 以及 __NUXT_VERSION__ 等全局变量。

Runtime (App) 属性：运行时代码的静态环境标志

以下属性会被静态注入到 Nuxt 应用的运行时代码中，可放心用于 tree-shaking：

属性	类型	描述
import.meta.client	boolean	在客户端（浏览器）环境中求值时为 true
import.meta.browser	boolean	在客户端（浏览器）环境中求值时为 true（与 client 等价）
import.meta.server	boolean	在服务端环境中求值时为 true
import.meta.nitro	boolean	在服务端（Nitro）环境中求值时为 true（与 server 等价）
import.meta.dev	boolean	运行 Nuxt dev server（开发模式）时为 true
import.meta.envName	string	当前 Nuxt 环境名称，包含通过 --envName 传入的自定义值
import.meta.test	boolean	在测试上下文运行时为 true
import.meta.prerender	boolean	在构建的预渲染阶段于服务端渲染 HTML 时为 true

对 process.* 旧标志的说明

官方文档特别提醒：process.browser、process.client、process.dev、process.server 和 process.test 自 Nuxt 3.12 起已被软弃用（soft-deprecated）。在 Nuxt 5 或启用 future.compatibilityVersion: 5 的情况下，Nuxt 不再向 NodeJS.Process 扩展这些属性，应优先使用上表中对应的 import.meta.* 标志；构建期的 process.* 定义仍会保留以兼容旧代码。

源码中的真实应用

这些标志在 Nuxt 运行时源码中被广泛使用，例如：

• nuxt-island.ts 用 import.meta.client 区分生成 island id 与注册组件映射表仅在客户端执行的逻辑；第 112 行又用 import.meta.server 决定服务端应走 useRequestFetch()、客户端走 $fetch。
• nuxt-root.vue 使用 import.meta.server 决定路由 URL 来自 nuxtApp.ssrContext.url 还是 window.location.pathname。
• idle-callback.ts 通过 import.meta.server 为服务端返回一个安全的空实现，避免 Node 环境不存在 requestIdleCallback。
• interval.ts 的报错提示中甚至建议开发者用 import.meta.client 包裹浏览器专属的 setInterval 调用。
• nuxt-error-page.vue 用 import.meta.dev 仅在开发模式展示堆栈信息。
• nuxt-link.ts 使用 import.meta.client 选择以 window.location.href 还是固定地址构造 new URL。

值得一提的还有 templates.ts 中 $fetch 的生成模板：import.meta.test ? globalThis.$fetch || ... : /*#__PURE__*/ _$fetch.create({...})——仅在测试环境才走 globalThis.$fetch 分支，生产环境则被替换为纯函数调用的 create，便于压缩器消除。

替换实现的来源

静态替换发生在构建阶段。Vite 一侧的 replace.ts 会遍历 Vite/Nuxt 的 define 配置中所有以 import.meta. 开头的键，并将其收集后交给 replacePlugin（以 preventAssignment: true 保证只替换 import.meta.xxx 的成员读取而不误伤赋值语句）。这也意味着你在自定义构建配置里以 define 声明自己的 import.meta.* 键时，会经由同一条管线生效。

Builder Properties：模块与配置文件中的属性

与上面仅面向运行时代码的属性不同，以下属性在**模块（modules）**和 nuxt.config 中同样可用：

属性	类型	描述
import.meta.env	object	等价于 process.env
import.meta.url	string	当前文件的可解析路径

import.meta.envName 的取值逻辑

envName 的默认值并非写死的字符串，而是在配置解析阶段根据 dev 推导。见 common.ts：当未显式传入字符串时，开发模式返回 'development'，否则返回 'production'；开发者也可以在 nuxt.config 中显式配置 envName，或通过 CLI 的 --envName 传入任意自定义环境名称，此时 import.meta.envName 在代码中即为该值。基于 import.meta.envName 而非 import.meta.dev 判断，可以区分出"生产但特定环境"（如 staging）等更细粒度场景。

实战示例：在模块中用 import.meta.url 解析文件路径

模块开发者最常见的需求之一，是相对于"当前模块文件所在目录"去解析其他文件。由于 nuxt.config 在加载时模块代码与运行目录可能并不一致，硬编码路径极易出错。官方推荐的写法是使用 createResolver(import.meta.url)：

import { createResolver } from 'nuxt/kit'

// Resolve relative from the current file
const resolver = createResolver(import.meta.url)

export default defineNuxtModule({
  meta: { name: 'myModule' },
  setup () {
    addComponent({
      name: 'MyModuleComponent',
      // Resolves to '/modules/my-module/components/MyModuleComponent.vue'
      filePath: resolver.resolve('./components/MyModuleComponent.vue'),
    })
  },
})

createResolver 接收 import.meta.url（当前模块文件的路径），随后通过 resolver.resolve(...) 得到的路径始终基于模块文件所在位置解析，无论项目根目录在哪都保持正确。createResolver 与 addComponent、defineNuxtModule 均来自 @nuxt/kit（即 nuxt/kit），可在文档 createResolver 相关模块 API 中查看更多配套用法。

使用建议小结

• 运行时代码统一用 import.meta.*：客户端/服务端分支判断优先使用 import.meta.client/import.meta.server（browser/nitro 为语义别名），环境区分使用 import.meta.dev，测试环境使用 import.meta.test；预渲染专用分支则使用 import.meta.prerender。
• 留意弃用项：process.browser 等旧式判断在 Nuxt 5 及 future.compatibilityVersion: 5 下不再被类型系统支持，应尽早迁移。
• 模块与配置中善用 import.meta.url：通过 createResolver 实现与工作目录无关的稳定路径解析，是编写可复用模块的关键习惯。