Webpack v5+React中如何用manifest.json映射带contenthash的静态资源路径？

核心误解纠正 #

你用<link rel="manifest">引入的是PWA Web App Manifest，和webpack-manifest-plugin生成的资源映射文件完全不是同一个东西——浏览器不会自动读取这个文件来替换页面中的资源路径，这是导致请求404的根本原因。

可行解决方案 #

方案1：自定义工具函数读取映射（推荐） #

修改代码中资源引用的方式，通过工具函数自动替换成带hash的路径：

1. 创建资源路径工具函数：

// src/utils/assetUrl.js
// 生产构建后manifest在dist目录，开发环境可直接返回原路径
import manifest from '../../dist/assets-manifest.json';

export const getAssetUrl = (originalPath) => {
  if (process.env.NODE_ENV === 'development') {
    return originalPath;
  }
  // 移除路径开头的/，匹配manifest中的键
  const key = originalPath.replace(/^\//, '');
  // 返回带hash的路径，不存在则返回原路径
  return manifest[key] ? `/${manifest[key]}` : originalPath;
};

2. 在组件中使用：

import { getAssetUrl } from './utils/assetUrl';

// 原写法：<img src="/img/home/desktop/image-hero.jpg" />
// 修改后：
<img src={getAssetUrl('/img/home/desktop/image-hero.jpg')} />

方案2：构建时自动替换路径 #

通过自定义Webpack Loader，在构建阶段直接把代码中的原路径替换成带hash的路径，无需修改业务代码：

1. 编写自定义Loader：

// loaders/replace-asset-path-loader.js
const fs = require('fs');
const path = require('path');

module.exports = function(source) {
  // 仅在生产环境执行替换
  if (this.mode !== 'production') {
    return source;
  }
  // 读取manifest文件
  const manifestPath = path.resolve(__dirname, '../dist/assets-manifest.json');
  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
  
  // 匹配所有/img/开头的绝对路径引用
  return source.replace(/src="(\/img\/[^"]+)"/g, (match, originalPath) => {
    const key = originalPath.replace(/^\//, '');
    const hashedPath = manifest[key];
    return hashedPath ? `src="/${hashedPath}"` : match;
  });
};

2. 在Webpack生产配置中添加Loader：

// webpack.prod.js
module.exports = {
  // ...其他配置
  module: {
    rules: [
      {
        test: /\.jsx?$/,
        use: [
          'babel-loader',
          path.resolve(__dirname, './loaders/replace-asset-path-loader.js')
        ],
        exclude: /node_modules/
      }
    ]
  }
};

方案3：运行时动态替换路径 #

在页面加载后，通过脚本读取manifest并替换所有图片的src属性，完全无需修改业务代码：

在HTML模板的</body>前添加：

<script>
  // 仅在生产环境执行
  if (window.location.hostname !== 'localhost') {
    fetch('/assets-manifest.json')
      .then(res => res.json())
      .then(manifest => {
        // 替换所有/img/开头的图片路径
        document.querySelectorAll('img[src^="/img/"]').forEach(img => {
          const originalPath = img.src.replace(window.location.origin, '');
          const key = originalPath.replace(/^\//, '');
          const hashedPath = manifest[key];
          if (hashedPath) {
            img.src = `/${hashedPath}`;
          }
        });
        // 如需替换CSS背景图等其他资源，可同理扩展
      })
      .catch(err => console.error('加载资源映射失败:', err));
  }
</script>

额外配置调整 #

1. 移除HTML中的无效manifest引用：
   删掉<link rel="manifest" href="assets-manifest.json">，这个是PWA专用配置，和资源映射无关。

2. 优化CopyPlugin配置：
   确保public文件夹中的文件被正确复制并添加hash：

new CopyPlugin({
  patterns: [
    { 
      from: 'public', 
      to: '[path][name].[contenthash][ext]',
      // 排除不需要添加hash的文件（如HTML模板）
      globOptions: {
        ignore: ['**/index.html']
      }
    }
  ]
})

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