Umi4 项目中正确引用 public 目录下的静态图片资源

在 Umi4 项目中，开发者有时会遇到引用 public 目录下静态图片资源的问题。本文将深入探讨这一问题的原因及解决方案，帮助开发者更好地理解 Umi4 的资源处理机制。

问题现象

在 Umi4 项目中，当尝试通过 import 语句引用 public 目录下的图片时：

import ref_dryer_alarm from '/static/ref_dryer_alarm.png';

系统可能会报错提示找不到模块。然而有趣的是，同样的配置在其他 Umi4 项目中却能正常工作。

问题根源分析

1. public 目录的特殊性
   public 目录下的文件会被直接复制到构建输出目录，不会经过 webpack 的处理流程。这意味着：

   • 文件不会被压缩或优化
   • 不会添加内容哈希
   • 保持原始文件名

2. import 语句的工作原理
   当使用 import 导入资源时，Umi/webpack 会尝试将这些资源作为模块处理。对于图片资源，webpack 通常会：

   • 对小图片进行 base64 内联
   • 对大图片进行复制并重命名（添加哈希）

3. 配置差异的影响
   不同项目的配置差异可能导致对 public 目录下资源的处理方式不同，特别是：

   • publicPath 设置
   • chainWebpack 自定义配置
   • 静态资源处理规则

解决方案

推荐方案：使用项目目录存放图片

将图片放在 src 目录下（如 src/assets），通过 import 引入：

import myImage from '@/assets/my-image.png';

Umi 会自动根据图片大小决定是否内联或复制到输出目录。

高级配置方案

如果需要严格控制图片处理方式，可以配置：

1. 调整内联阈值：

// .umirc.ts
export default {
  inlineLimit: 0 // 设置为0表示所有图片都不内联
}

2. 自定义资源处理规则：

chainWebpack(config) {
  config.module
    .rule('images')
    .test(/\.(png|jpe?g|gif|svg|webp)$/)
    .type('asset/resource')
    .set('generator', {
      filename: 'static/[name][ext]'
    });
}

public 目录的正确使用方式

如果确实需要使用 public 目录，建议：

1. 直接使用完整路径引用：

<img src="/static/my-image.png" />

2. 避免使用 import 语句引用 public 目录文件

最佳实践建议

1. 项目结构规划：

   • 将需要频繁更新的资源放在 public 目录
   • 将需要打包优化的资源放在 src 目录

2. 构建优化：

   • 合理设置 inlineLimit 平衡性能和请求数量
   • 为生产环境配置合理的缓存策略

3. 开发调试：

   • 使用环境变量区分开发和生产环境的资源引用方式
   • 定期检查构建输出目录确认资源处理结果

通过理解 Umi4 的资源处理机制并合理配置，开发者可以高效地管理项目中的静态资源，避免常见的引用问题。