Next.js应用如何获取并展示Git版本？github.sha始终为undefined

问题核心原因 #

你遇到的NEXT_PUBLIC_APP_VERSION始终为undefined，大概率是环境变量没有在构建阶段正确注入导致的。Next.js对NEXT_PUBLIC_前缀的变量有严格的时机要求：这类变量必须在next build执行时就已存在，才能被打包进客户端代码。

具体解决办法 #

1. 修正CI/CD流程中的环境变量传递

如果用GitHub Actions，确保环境变量是在next build命令的env块中定义的，避免因时机不对导致变量未注入。示例配置：

steps:
  - name: 拉取代码
    uses: actions/checkout@v4
  - name: 配置Node.js环境
    uses: actions/setup-node@v4
    with:
      node-version: 20
  - name: 安装依赖
    run: npm install
  - name: 构建Next.js应用
    env:
      NEXT_PUBLIC_APP_VERSION: ${{ github.sha }}
    run: npm run build

本地测试时，需要手动在构建前设置变量：

# macOS/Linux
NEXT_PUBLIC_APP_VERSION=$(git rev-parse HEAD) npm run build && npm start

# Windows（PowerShell）
$env:NEXT_PUBLIC_APP_VERSION=(git rev-parse HEAD); npm run build; npm start

注意：开发模式（npm run dev）不会读取构建时的变量，必须启动生产服务（npm start）才能看到效果。

2. 验证变量是否成功注入

构建完成后，打开.next/static/chunks/pages/_app.js（或对应页面的chunk文件），搜索NEXT_PUBLIC_APP_VERSION，如果能看到实际的提交哈希，说明注入成功；如果还是变量名本身，说明环境变量传递有误。

3. 替代方案：生成静态版本文件

如果环境变量方式始终有问题，可以在构建前生成一个静态文件存储哈希：

• 在package.json的scripts中添加预构建命令：

  "scripts": {
    "prebuild": "echo '{\"commitHash\": \"'$(git rev-parse HEAD)'\"}' > public/version.json",
    "build": "next build",
    // 其他脚本...
  }
  

• 在客户端组件中读取这个文件：

  import { useEffect, useState } from 'react';
  
  export default function VersionBadge() {
    const [commitHash, setCommitHash] = useState('');
  
    useEffect(() => {
      fetch('/version.json')
        .then(res => res.json())
        .then(data => setCommitHash(data.commitHash.slice(0, 7))); // 只显示前7位哈希
    }, []);
  
    return commitHash ? <span className="version-badge">Commit: {commitHash}</span> : null;
  }
  

• 服务端组件可以直接读取文件：

  import fs from 'fs/promises';
  import path from 'path';
  
  export default async function VersionBadge() {
    const filePath = path.join(process.cwd(), 'public', 'version.json');
    const fileContent = await fs.readFile(filePath, 'utf8');
    const { commitHash } = JSON.parse(fileContent);
  
    return <span>Commit: {commitHash.slice(0, 7)}</span>;
  }
  

常见误区提醒 #

• 不要在npm run dev中测试构建时的变量：开发模式是实时编译，变量在启动时注入，和构建阶段的变量无关。
• 务必保留NEXT_PUBLIC_前缀：不带这个前缀的环境变量只能在服务端代码中访问，无法传递到客户端组件。

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