Next.js 构建ID的获取、配置与前端展示指南

npm install next-build-id
# 或
yarn add next-build-id

// next.config.js
const nextBuildId = require('next-build-id');

module.exports = {
  // generateBuildId 选项允许您自定义构建ID的生成逻辑
  // next-build-id 包会返回一个 Promise，这里我们使用 await
  generateBuildId: async () => {
    // next-build-id 会根据当前 Git 状态生成一个 ID
    const buildId = await nextBuildId({ dir: __dirname });
    return buildId;
  },

  // 通过 env 属性将构建ID注入到环境变量中
  // 注意：这里的 buildId 是 generateBuildId 返回的值
  // 为了在客户端访问，必须以 NEXT_PUBLIC_ 开头
  env: {
    NEXT_PUBLIC_APP_BUILD_ID: process.env.NEXT_PUBLIC_APP_BUILD_ID, // 确保在外部构建时可以覆盖
  },

  // 如果您希望直接使用 nextBuildId 生成的值，可以这样配置
  // 注意：这种方式 generateBuildId 依然会被调用，但 env 中可能需要单独处理
  async rewrites() {
    const buildId = await nextBuildId({ dir: __dirname });
    return {
      beforeFiles: [],
      afterFiles: [],
      fallback: [],
    };
  },
};

// 实际操作中，为了将 generateBuildId 的结果传递给 env，
// 最直接的方式是在 generateBuildId 内部设置一个全局可访问的变量
// 或者通过一个同步函数来获取，但 next-build-id 是异步的。
// 更推荐的做法是：在构建脚本中设置环境变量，或者直接在 next.config.js 顶部同步获取。
// 考虑到 next-build-id 是异步的，我们可以这样优化 next.config.js：

const nextBuildId = require('next-build-id');

// 同步获取 buildId，但这要求在 next.config.js 被加载时 Git 仓库是可用的
// 如果 nextBuildId 内部是异步的，这里会是一个 Promise。
// Next.js 的 generateBuildId 选项是期望一个返回 Promise 的函数。
// 而 env 选项是静态配置的。
// 最稳妥的办法是：在 generateBuildId 中生成 ID，并在运行时通过 process.env 获取。

// 修正后的 next.config.js 示例，确保 env 变量可用
module.exports = {
  // generateBuildId 将被 Next.js 调用以获取构建ID
  generateBuildId: async () => {
    const id = await nextBuildId({ dir: __dirname });
    // 您可以在这里将 ID 存储到某个地方，或者直接返回
    // 但要将其暴露给客户端，需要通过 env 属性
    return id;
  },

  // 关键：在构建时将 buildId 注入到环境变量中
  // 这里的 NEXT_PUBLIC_APP_BUILD_ID 应该在构建前被设置，
  // 或者直接使用一个在 generateBuildId 内部设置的全局变量 (不推荐)
  // 最简单的方式是让 generateBuildId 返回的 ID 成为 Next.js 内部的 buildId，
  // 然后我们通过一个在构建时确定的环境变量来暴露一个 "副本"。
  // 
  // 我们可以通过在 next.config.js 外部获取 buildId 并传递给 env。
  // 但是 nextBuildId 是异步的，env 是同步的。
  //
  // 最佳实践是：在 generateBuildId 中返回 ID，然后通过一个脚本在构建前设置一个环境变量。
  // 或者，我们可以利用 next.config.js 的灵活性，在 env 中直接调用 nextBuildId (但它会执行两次)
  // 或者，如果 buildId 仅用于显示，且不要求与 Next.js 内部的 buildId 严格一致，
  // 我们可以直接在 env 中生成一个。

  // 考虑到用户希望在客户端显示，最直接的办法是：
  // 1. 在 next.config.js 顶部同步获取 buildId (如果 next-build-id 支持)
  // 2. 将其作为 env 变量。
  // 
  // 鉴于 next-build-id 是异步的，而 env 是同步的，
  // 最简单且兼容性好的方案是：在 `generateBuildId` 中返回 ID，
  // 然后在 `env` 中引用一个在**构建时**已经存在的环境变量。
  // 
  // 假设我们希望 `NEXT_PUBLIC_APP_BUILD_ID` 能够与 `generateBuildId` 返回的值一致，
  // 那么我们需要在 Next.js 构建命令之前，先运行一个脚本来获取这个 ID 并将其设置为环境变量。
  // 
  // 例如，在 package.json 中：
  // "scripts": {
  //   "build": "node scripts/set-build-id.js && next build",
  //   "dev": "next dev"
  // }
  //
  // scripts/set-build-id.js:
  // const nextBuildId = require('next-build-id');
  // async function setBuildId() {
  //   const id = await nextBuildId({ dir: process.cwd() });
  //   process.env.NEXT_PUBLIC_APP_BUILD_ID = id;
  //   console.log(`Set NEXT_PUBLIC_APP_BUILD_ID to: ${id}`);
  // }
  // setBuildId();
  // 
  // 然后 next.config.js 就可以这样写：
  env: {
    NEXT_PUBLIC_APP_BUILD_ID: process.env.NEXT_PUBLIC_APP_BUILD_ID,
  },
};

// next.config.js
const nextBuildId = require('next-build-id');

// 注意：如果 nextBuildId 是异步的，这里会得到一个 Promise。
// env 属性需要同步值，因此这可能不是最佳实践。
// 更好的方法是使用 generateBuildId 配合一个在构建前设置的环境变量。
//
// 为了教程的简洁性，我们假设 nextBuildId 可以同步执行或其结果可同步获取。
// 实际上，next-build-id 包是异步的。
//
// 最符合 Next.js 推荐的方式是：
// generateBuildId 负责返回 Next.js 内部使用的 build ID。
// env 变量用于暴露给客户端的额外信息。
// 如果您想让两者保持一致，需要确保 env 中的变量在构建时被正确设置。

// 推荐的 next.config.js 配置方式：
// 1. generateBuildId 异步返回 ID 给 Next.js 内部使用。
// 2. 在 env 中，我们引用一个在构建时通过其他方式（例如构建脚本）设置的环境变量。
//    如果这个变量在构建前没有被设置，它将是 undefined。

module.exports = {
  generateBuildId: async () => {
    // 这个 ID 会被 Next.js 内部使用，例如在 .next/BUILD_ID 文件中
    const id = await nextBuildId({ dir: __dirname });
    console.log(`Next.js 内部 Build ID: ${id}`);
    return id;
  },

  // 将一个在构建时已存在的环境变量暴露给客户端
  // 假设您在构建前通过脚本设置了 NEXT_PUBLIC_APP_BUILD_ID
  env: {
    NEXT_PUBLIC_APP_BUILD_ID: process.env.NEXT_PUBLIC_APP_BUILD_ID || 'development-build-id',
  },
};

// pages/api/build-info.js
export default function handler(req, res) {
  const buildId = process.env.NEXT_PUBLIC_APP_BUILD_ID;
  res.status(200).json({ buildId });
}

// pages/index.js (getServerSideProps)
export async function getServerSideProps(context) {
  const buildId = process.env.NEXT_PUBLIC_APP_BUILD_ID;
  return {
    props: {
      buildId,
    },
  };
}

// components/BuildInfo.js
import React, { useEffect } from 'react';

const BuildInfo = () => {
  const buildId = process.env.NEXT_PUBLIC_APP_BUILD_ID;

  useEffect(() => {
    // 在浏览器控制台显示构建ID
    console.log('Next.js Build ID:', buildId);
  }, [buildId]);

  return (
    <div>
      <p>当前构建ID: {buildId || '未知'}</p>
      <p>请查看浏览器控制台获取更多信息。</p>
    </div>
  );
};

export default BuildInfo;

// pages/index.js
import BuildInfo from '../components/BuildInfo';

export default function HomePage() {
  return (
    <div>
      <h1>欢迎来到我的 Next.js 应用</h1>
      <BuildInfo />
    </div>
  );
}