React/Express项目图片加载失败排查求助

React/Express 应用中CSS样式正常加载，但图片无法显示，页面提示“could not load the image”，怀疑是服务器静态文件配置或Webpack打包配置问题。

Express 服务器代码 #

import express from 'express';
import ReactDOM from 'react-dom/server';
import { indexTemplate } from './indexTemplate';
import App from "../App";

const app = express();

app.use('/static', express.static('./dist/client'));

app.get('/', (req, res) => {
  res.send(
    indexTemplate(ReactDOM.renderToString(App()),)
  );
});

app.listen(3000, () => {
  console.log('Server started, on http://localhost:3000');
});

CSS 背景图代码 #

.main {
    display: block;
    width: 100%;
    height: 500px;
    background: url("../../static/img1.jpg");
    background-size: cover;
}

客户端 Webpack 配置 #

const path = require( 'path' );
const { HotModuleReplacementPlugin } = require( 'webpack' );
const { CleanWebpackPlugin } = require( 'clean-webpack-plugin' );

const NODE_ENV = process.env.NODE_ENV;
const IS_DEV = NODE_ENV === 'development';
const IS_PROD = NODE_ENV === 'production';
const GLOBAL_CSS_REGEXP = /\.global\.css$/;

function setupDevtool() {
  if ( IS_DEV ) {
    return 'eval';
  }

  if ( IS_PROD ) {
    return false;
  }
}

module.exports = {
  mode: NODE_ENV ? NODE_ENV : 'development',
  resolve: {
    extensions: [ '.js', '.jsx', '.ts', '.tsx', '.json' ],
    alias: {
      'react-dom': 'react-dom',
    }
  },
  entry: [
    path.resolve( __dirname, '../src/client/index.jsx' ),
    'webpack-hot-middleware/client?path=http://localhost:3001/static/__webpack_hmr',
  ],
  output: {
    path: path.resolve( __dirname, '../dist/client' ),
    filename: 'client.js',
    publicPath: '/static/',
  },
  module: {
    rules: [
      {
        test: /\.[tj]sx?$/,
        use: [ 'ts-loader' ]
      },
      {
        test: /\.css$/,
        use: [
          'style-loader',
          {
            loader: 'css-loader',
            options: {
              modules: {
                mode: 'local',
                localIdentName: '[name]__[local]--[hash:base64:5]'
              }
            }
          }
        ],
        exclude: GLOBAL_CSS_REGEXP
      },
      {
        test: GLOBAL_CSS_REGEXP,
        use: [ 'style-loader', 'css-loader' ]
      },
      {
        test: /\.(jpe?g|gif|png|svg)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              limit: 10000
            }
          }
        ]
      }
    ]
  },
  devtool: setupDevtool(),
  plugins: IS_DEV
    ? [
      new CleanWebpackPlugin(),
      new HotModuleReplacementPlugin(),
    ]
    : [],
};

服务端 Webpack 配置 #

const path = require("path");
const nodeExternals = require("webpack-node-externals");
const NODE_ENV = process.env.NODE_ENV;
const GLOBAL_CSS_REGEXP = /\.global\.css$/;


module.exports = {
  target: "node",
  mode: NODE_ENV ?? "development",
  entry: path.resolve(__dirname, "../src/server/server.js"),
  output: {
    path: path.resolve(__dirname, "../dist/server"),
    filename: "server.js",
  },
  externals: [nodeExternals()],
  module: {
    rules: [
      {
        test: /\.[tj]sx?$/,
        use: [ 'ts-loader' ]
      },
      {
        test: /\.css$/,
        use: [
          'style-loader',
          {
            loader: 'css-loader',
            options: {
              modules: {
                mode: 'local',
                localIdentName: '[name]__[local]--[hash:base64:5]'
              }
            }
          }
        ],
        exclude: GLOBAL_CSS_REGEXP
      },
      {
        test: GLOBAL_CSS_REGEXP,
        use: [ 'style-loader', 'css-loader' ]
      },
      {
        test: /\.(jpe?g|gif|png|svg)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              limit: 10000
            }
          }
        ]
      }
    ]
  },
  resolve: {
    extensions: [".ts", ".tsx", ".js", ".jsx", ".json"],
  },
};

修复步骤 #

1. 修正 Express 静态文件路径 #

express.static 使用相对路径可能因启动目录不同导致找不到文件，换成绝对路径：

import path from 'path';
// 根据实际文件层级调整路径，确保指向 dist/client 目录
app.use('/static', express.static(path.resolve(__dirname, '../../dist/client')));

2. 调整 CSS 中的图片引用路径 #

Webpack 编译时会重写资源路径，当前相对路径会导致最终URL错误，改为基于 publicPath 的绝对路径：

background: url("/static/img1.jpg");

3. 完善客户端 Webpack 图片 loader 配置 #

url-loader 需指定输出路径和公共路径，确保大图片生成的URL正确指向静态资源目录：

{
  test: /\.(jpe?g|gif|png|svg)$/i,
  use: [
    {
      loader: 'url-loader',
      options: {
        limit: 10000,
        outputPath: 'img/', // 图片输出到 dist/client/img 目录
        publicPath: '/static/img/' // 生成的URL前缀
      }
    }
  ]
}

同时确保图片文件放在 src/client 目录下，让Webpack能正确打包拷贝。

4. 修正服务端 Webpack 配置 #

服务端不需要处理浏览器端资源，替换图片和CSS的loader：

1. 安装 null-loader：

npm install null-loader --save-dev

2. 修改服务端Webpack规则：

// 忽略图片资源
{
  test: /\.(jpe?g|gif|png|svg)$/i,
  use: 'null-loader'
},
// 服务端仅处理CSS模块映射，不生成样式
{
  test: /\.css$/,
  use: [
    {
      loader: 'css-loader',
      options: {
        modules: {
          mode: 'local',
          localIdentName: '[name]__[local]--[hash:base64:5]'
        },
        exportOnlyLocals: true
      }
    }
  ],
  exclude: GLOBAL_CSS_REGEXP
},
{
  test: GLOBAL_CSS_REGEXP,
  use: 'null-loader'
}

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