Next.js如何添加客户端可访问的隐藏应用版本信息

以下方案均满足「普通用户无感知、可快速检索版本、实现规范无侵入」的要求，适配App Router和Pages Router两种路由模式：

方案1：自定义命名空间Meta标签（语义合规，推荐优先使用） #

你担心的非标准meta标签问题，本质是直接给meta加无定义属性不符合规范，只要给name属性加自定义前缀做命名空间，就完全符合HTML标准，不会和现有标准meta语义冲突。

• App Router 实现：直接在根layout的元数据配置中添加自定义项

// app/layout.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  // 其他原有元数据配置
  other: {
    'x-app-version': process.env.npm_package_version || 'unknown',
  }
}

• Pages Router 实现：在自定义_document.tsx的Head中插入标签

// pages/_document.tsx
import { Html, Head, Main, NextScript } from 'next/document'

export default function Document() {
  return (
    <Html lang="zh-CN">
      <Head>
        <meta name="x-app-version" content={process.env.npm_package_version || 'unknown'} />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

检索方式：浏览器控制台直接执行以下代码即可获取版本号，普通用户浏览页面时完全不可见。

document.querySelector('meta[name="x-app-version"]')?.content

方案2：全局属性挂载（零DOM侵入，最简洁） #

完全不需要新增DOM节点，直接把版本信息挂载到全局对象上，没有任何语义问题，也不会影响页面渲染或无障碍识别。

• App Router 实现：在客户端根Provider中注入

// app/providers.tsx
'use client'

export default function Providers({ children }: { children: React.ReactNode }) {
  if (typeof window !== 'undefined') {
    window.__APP_VERSION__ = process.env.npm_package_version || 'unknown'
    // 也可以挂载到html标签的dataset上，避免全局变量污染
    // document.documentElement.dataset.appVersion = process.env.npm_package_version || 'unknown'
  }
  return <>{children}</>
}

在根layout中引入Providers组件包裹所有页面内容即可生效。

• Pages Router 实现：直接在_app.tsx入口注入

// pages/_app.tsx
import type { AppProps } from 'next/app'

if (typeof window !== 'undefined') {
  window.__APP_VERSION__ = process.env.npm_package_version || 'unknown'
}

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

检索方式：控制台直接执行window.__APP_VERSION__即可获取版本，若挂载在dataset上则执行document.documentElement.dataset.appVersion获取。

方案3：HTML注释注入（适配注释存储需求） #

Next.js没有屏蔽React根节点处的注释输出，不需要修改构建配置，直接在根layout中写JSX注释，构建后就会保留在最终输出的HTML源码中。

// app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="zh-CN">
      {/* APP_VERSION: v{process.env.npm_package_version || 'unknown'} */}
      <body>{children}</body>
    </html>
  )
}

检索方式：控制台执行正则匹配即可提取版本：

document.documentElement.outerHTML.match(/APP_VERSION: v([\d.]+)/)?.[1]

该方式需要正则匹配，检索成本略高于前两种方案，适合偏好注释存储的场景。

注：process.env.npm_package_version是Node.js运行时自动注入的环境变量，会直接读取项目package.json中配置的version字段，不需要手动额外配置。如果需要使用CI/CD流程生成的构建版本号，替换成对应流水线注入的环境变量即可。

针对你之前考虑的三种思路的补充说明：

• 直接写<meta version="1.2.3">不符合HTML规范，meta标签必须携带name/property/http-equiv三者之一才合法，加自定义前缀的name属性即可解决合规问题。
• Next.js添加HTML注释不需要特殊配置，根节点处的JSX注释会被直接输出到最终HTML中。
• 隐藏div的方式不推荐，会额外增加DOM节点，还可能被无障碍读屏工具捕获，存在不必要的副作用。

内容的提问来源于stack exchange，提问作者kca