React 17服务端渲染(SSR)时图片无法加载如何解决

问题背景 #

当前基于Express搭建的React SSR服务已实现CSS服务端渲染、客户端hydrate注水逻辑，但页面图片资源始终无法加载，核心代码如下：
server/server.js 服务端逻辑：

import path from 'path';
import fs from 'fs';

import React from 'react';
import ReactDOMServer from 'react-dom/server';
import express from 'express';

import App from '../src/App';

const PORT = process.env.PORT || 1234;
const app = express();

// ...

app.get('/', (req, res) => {
    const app = ReactDOMServer.renderToString(<App />);
    const indexFile = path.resolve('./build/index.html');
  
    fs.readFile(indexFile, 'utf8', (err, data) => {
      if (err) {
        console.error('Something went wrong:', err);
        return res.status(500).send("Oops, better luck next time!");
      }
  
      return res.send(
        data.replace('<div id="root"></div>', `<div id="root">${app}</div>`)
      );
    });
  });
  
  app.use(express.static('./build'));
  
  app.listen(PORT, () => {
    console.log(`Server is listening on port ${PORT}`);
  });

server/index.js 启动配置：

require('ignore-styles')

require('@babel/register')({
    ignore: [/(node_module)/],
    presets: ['@babel/preset-env', '@babel/preset-react']
})

require('./server')

故障根因 #

• 中间件顺序错误：静态资源托管规则写在页面路由之后，图片等静态请求可能被页面渲染逻辑拦截，无法走到静态资源返回流程
• 服务端缺少非JS资源解析逻辑：@babel/register默认只处理JS/JSX文件，组件中import的图片、字体等资源没有对应解析规则，服务端渲染时会拿到错误的资源引用值
• 代码存在变量名遮蔽问题：app.get回调内声明的const app变量和外层express实例同名，虽然作用域隔离不直接报错，但容易引发不可预期的逻辑异常
• 路径配置不统一：静态资源托管、打包配置的资源公共路径如果存在相对路径配置，会导致嵌套路由下图片路径拼接错误

修复步骤 #

1. 调整中间件顺序+修复变量名冲突 #

将静态资源托管中间件移到所有业务路由之前，同时修改渲染结果的变量名，避免和express实例重名：

const PORT = process.env.PORT || 1234;
const app = express();

// ... 其他全局中间件

// 静态资源托管放在最前面，优先处理静态资源请求
app.use(express.static(path.resolve('./build')));

app.get('/', (req, res) => {
    // 修改变量名，避免和外层app实例冲突
    const appContent = ReactDOMServer.renderToString(<App />);
    const indexFile = path.resolve('./build/index.html');
  
    fs.readFile(indexFile, 'utf8', (err, data) => {
      if (err) {
        console.error('SSR render error:', err);
        return res.status(500).send('Server error');
      }
  
      return res.send(
        data.replace('<div id="root"></div>', `<div id="root">${appContent}</div>`)
      );
    });
  });

app.listen(PORT, () => {
  console.log(`Server is listening on port ${PORT}`);
});

2. 增加服务端静态资源解析支持 #

安装资源处理依赖，让服务端可以正确识别图片等非JS资源的import逻辑，返回正确的访问路径：

npm i asset-require-hook -D

修改启动配置文件server/index.js，在加载babel转译规则前增加资源解析hook：

require('ignore-styles')

// 新增：处理图片、字体等静态资源的require解析
require('asset-require-hook')({
  extensions: ['jpg', 'jpeg', 'png', 'gif', 'svg', 'webp'],
  // 保持和前端打包配置的publicPath一致，默认用根路径
  publicPath: '/'
})

require('@babel/register')({
    ignore: [/(node_module)/],
    presets: ['@babel/preset-env', '@babel/preset-react']
})

require('./server')

3. 校验路径配置一致性 #

确认前端打包配置（CRA/webpack/vite等）的资源公共路径publicPath为绝对路径/，不要使用相对路径./，避免子路由场景下图片相对路径拼接错误。

4. 校验构建产物 #

执行前端构建命令后，检查build目录下是否存在对应的图片资源，资源路径和服务端返回的HTML中的图片引用路径是否匹配。

注意：CSS中引用的背景图不受ignore-styles影响，客户端hydrate完成后会自动从静态资源目录加载对应图片，只要静态资源路由配置正确即可正常显示。

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