如何解决TypeScript服务端用asset/resource加载图片时ts-node模块识别问题

问题场景 #

用React、TypeScript和Webpack 5构建SSR应用时，在视图中用asset/resource加载图片，一开始客户端构建报错：

Cannot find module '../../assets/images/demo.png' or its corresponding type declarations.

按照建议在d.ts中声明了图片扩展名模块后，VS Code的错误消失，客户端构建正常，但用ts-node编译服务端时，这个错误依然存在。

相关代码 #

类型声明文件（d.ts）

declare module '*.png';
declare module '*.jpg';
declare module '*.svg';
declare module '*.gif';

declare module 'asset-require-hook'; // 计划用于服务端加载文件名

Webpack配置

const config = {
  entry: entryPoints,
  mode: 'development',
  output: {
    filename: '[name].js',
    path: path.resolve(__dirname, './public/assets'),
    publicPath: '/',
  },
  resolve: {
    extensions: ['.ts', '.tsx', '.js'],
  },
  optimization: {
    splitChunks: {
      chunks: "all",
      cacheGroups: {
        vendor: {
          name: 'vendor',
          chunks: 'all',
          reuseExistingChunk: true,
          minChunks: Object.keys(entryPoints).length * 0.8,
          filename: '[name].js',
          test: /[\\/]node_modules[\\/]/,
        },
      }
    },
  },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader',
      },
      {
        test: /\.(s*)css$/,
        use: [
          MiniCssExtractPlugin.loader,
          'css-loader',
          'sass-loader',
        ],
      },
      {
        test: /\.(png|gif|jpg|svg)$/,
        type: 'asset/resource',
        generator: {
          filename: 'images/[name].[hash][ext]',
          emit: true,
        },
      },
    ],
  },
  plugins: [
    new MiniCssExtractPlugin(),
  ],
}

问题原因 #

1. ts-node的类型加载机制：ts-node默认只会加载入口文件直接或间接依赖的模块，不会主动扫描项目中所有的.d.ts文件；而客户端的Webpack通过ts-loader处理时，会遵循tsconfig.json的include配置，自动识别这些类型声明。
2. 服务端无Webpack处理图片：即使类型声明被识别，服务端运行时没有Webpack的asset/resource loader处理图片文件，还需要额外配置运行时的加载逻辑。

解决方案 #

1. 确保d.ts被TypeScript识别 #

检查项目根目录的tsconfig.json，确保include字段包含你的.d.ts文件路径：

{
  "include": [
    "src/**/*", // 项目源码路径
    "./typings/**/*.d.ts" // 若d.ts放在typings文件夹下，按需调整路径
    // 若d.ts在根目录，可写"./*.d.ts"
  ]
}

2. 配置ts-node加载所有类型文件 #

两种方式二选一：

• 命令行参数：运行ts-node时加上--files参数，强制加载所有类型声明文件：

  ts-node --files server.ts
  

• tsconfig配置：在tsconfig.json中添加ts-node的配置，永久开启files选项：

  {
    "ts-node": {
      "files": true
    },
    // 其他TypeScript配置...
  }
  

3. 服务端运行时处理图片加载 #

既然你计划用asset-require-hook，可以在服务端入口文件的最顶部引入并配置，让服务端加载图片时返回和客户端一致的路径：

const hook = require('asset-require-hook');
hook({
  extensions: ['png', 'jpg', 'svg', 'gif'],
  // 路径要和Webpack中generator.filename对应，加上publicPath
  name: '/assets/images/[name].[hash][ext]'
});

这样配置后，ts-node就能识别图片模块的类型声明，同时服务端也能正确处理图片的加载逻辑。

内容的提问来源于stack exchange，提问作者Diego Rodríguez