如何为NextJS 12构建的JS/CSS文件添加时间戳请求参数？

如果你需要让Next.js构建后的JS、CSS资源URL带上?ts=[时间戳/哈希]格式的请求参数，以下是两种可行的实现方案：

方案1：自定义Webpack配置（适配所有Next.js版本） #

Next.js允许在next.config.js中扩展Webpack配置，我们可以通过修改资源输出规则和HTML模板来追加参数：

实现代码 #

/** @type {import('next').NextConfig} */
// 生成构建时间戳（或用Git commit哈希替代）
const buildTimestamp = Date.now().toString();
// 若用Git哈希，先安装git-rev-sync：npm i git-rev-sync
// const { short } = require('git-rev-sync');
// const buildHash = short();

const nextConfig = {
  webpack: (config, { isServer, dev }) => {
    // 仅生产构建生效，开发环境无需缓存击穿
    if (!dev && !isServer) {
      // 修改静态资源的公共路径，为JS/CSS追加参数
      const originalPublicPath = config.output.publicPath;
      config.output.publicPath = (resourcePath) => {
        if (/\.js$|\.css$/.test(resourcePath)) {
          return `${originalPublicPath}${resourcePath}?ts=${buildTimestamp}`;
        }
        return `${originalPublicPath}${resourcePath}`;
      };

      // 修正HTML模板中的资源引用，确保所有JS/CSS链接都带上参数
      config.plugins.forEach(plugin => {
        if (plugin.constructor.name === 'HtmlWebpackPlugin') {
          plugin.hooks.afterTemplateExecution.tap('AddTimestampToAssets', (data) => {
            data.html = data.html.replace(
              /(\.js|\.css)(?="|<\/script>|<\/link>)/g,
              `$1?ts=${buildTimestamp}`
            );
          });
        }
      });
    }
    return config;
  },
};

module.exports = nextConfig;

方案2：利用Next.js内置的generateBuildId（更优雅的哈希方案） #

Next.js的generateBuildId可以生成自定义构建ID，用这个ID作为参数值，能保证每次构建的参数唯一，比时间戳更适合作为缓存标识：

实现代码 #

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 自定义构建ID，这里用时间戳，也可以换成Git commit哈希
  generateBuildId: async () => {
    return Date.now().toString();
    // return require('git-rev-sync').short();
  },
  webpack: (config, { buildId, isServer, dev }) => {
    if (!dev && !isServer) {
      config.output.publicPath = (resourcePath) => {
        if (/\.js$|\.css$/.test(resourcePath)) {
          return `${config.output.publicPath}${resourcePath}?ts=${buildId}`;
        }
        return `${config.output.publicPath}${resourcePath}`;
      };

      // 处理HTML中的资源引用
      config.plugins.forEach(plugin => {
        if (plugin.constructor.name === 'HtmlWebpackPlugin') {
          plugin.hooks.afterTemplateExecution.tap('AddBuildIdToAssets', (data) => {
            data.html = data.html.replace(
              /(\.js|\.css)(?="|<\/script>|<\/link>)/g,
              `$1?ts=${buildId}`
            );
          });
        }
      });
    }
    return config;
  },
};

module.exports = nextConfig;

关键注意点 #

• 开发环境跳过：通过!dev判断只在生产构建时添加参数，避免干扰热更新。
• CDN适配：如果用CDN，要确保CDN支持按完整URL缓存（包含查询参数），否则缓存击穿的效果会失效。
• 扩展资源范围：如果需要给图片、字体等其他静态资源也加参数，修改正则表达式为/\.(js|css|png|jpg|woff2)$/即可。

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