Umi.js 静态资源管理与最佳实践指南

静态资源分类与使用方式

在 Umi.js 项目中，静态资源管理主要分为两种类型，开发者需要根据实际需求选择合适的方式。

项目内资源（推荐方式）

这类资源通常放置在 src 目录下，如 src/assets 文件夹中。这是 Umi.js 推荐的主要使用方式，具有以下特点：

1. 自动处理机制：通过 ES6 的 import 语法导入，Umi 会自动处理资源路径
2. 内容哈希：构建时会自动添加哈希值，有效解决缓存问题
3. 路径解析：自动处理 base 路径，适合部署到子目录的场景

使用示例：

import imageUrl from '@/assets/image.png';

function Component() {
  return <img src={imageUrl} />;
}

公共目录资源

放置在 public 目录下的资源会直接拷贝到构建输出目录，适用于：

1. 完全静态不变的资源（如 favicon）
2. 版本化命名的第三方库（如 jquery.v1.0.0.js）
3. 需要直接通过绝对路径访问的资源

使用注意事项：

/* 直接使用绝对路径 */
background: url('/image.png');

实际开发中的经验与技巧

图标库的特殊处理

在使用类似 Ant Design 的图标组件时，开发者常会遇到需要引用外部脚本的情况。以下是几种处理方案：

1. 直接导入方案（简单但不推荐）

import iconUrl from '@/assets/icon.js';
Icon.createFromIconfontCN({ scriptUrl: iconUrl });

缺点：会导致图标脚本被打包到主 bundle 中，影响缓存策略。

2. 哈希复制方案（推荐）

// 配置文件中
const iconHash = createHash('md5').update(fs.readFileSync('icon.js')).digest('hex').slice(0, 8);

export default defineConfig({
  define: {
    'process.env.ICON_PATH': `${publicPath}icon.${iconHash}.js`,
  },
  copy: [{ from: 'icon.js', to: `dist/icon.${iconHash}.js` }]
});

// 组件中
Icon.createFromIconfontCN({ scriptUrl: `${process.env.ICON_PATH}` });

优点：独立文件，哈希稳定，缓存友好。

路径解析的注意事项

1. 在 CSS 中使用相对路径时，Umi 会自动解析为正确路径
2. 在 JavaScript 中动态构建路径时，需要考虑 base 路径的影响
3. 生产环境和开发环境的路径处理可能存在差异

性能优化建议

1. 合理分片：将大尺寸资源与代码分离，利用浏览器并行加载
2. 缓存策略：对频繁更新的资源使用哈希命名，对稳定资源使用长期缓存
3. 按需加载：对于非关键资源使用动态导入

常见问题排查

1. 资源加载404：检查路径是否正确，特别是部署到子目录时的 base 配置
2. 哈希变化异常：确认文件内容是否真的发生变化
3. 样式资源丢失：检查 CSS 中的相对路径是否正确解析

通过合理运用 Umi.js 的静态资源管理机制，开发者可以构建出高性能、易维护的前端应用。建议优先使用项目内资源导入方式，仅在特殊场景下使用 public 目录方案。