Docusaurus 中如何自定义图片资源的输出名称

在 Docusaurus 项目中，默认情况下会对图片资源添加哈希值作为文件名的一部分。这一设计主要是为了缓存优化考虑，确保当图片内容发生变化时，浏览器能够获取最新的资源版本。

默认行为分析

Docusaurus 使用 Webpack 处理静态资源时，默认配置会对图片文件名添加哈希值。例如，一个名为 example.png 的图片在构建后可能会变成 example.abc123.png 这样的形式。

这种哈希机制带来了以下优势：

1. 长期缓存 - 当图片内容不变时，浏览器可以重复使用缓存
2. 缓存失效 - 当图片内容更新时，哈希值会变化，确保用户获取最新版本

自定义配置方案

虽然默认行为对大多数项目有利，但在某些特定场景下，开发者可能需要移除这个哈希值。例如：

• 需要固定URL地址用于外部引用
• 与其他系统集成时需要保持文件名不变
• 开发环境调试时希望保持资源路径稳定

Docusaurus 提供了两种主要的解决方案：

方案一：使用静态文件夹

最简单的方法是将图片放置在 static 目录下。这个目录中的内容会被直接复制到构建输出目录，不会经过Webpack处理，因此不会添加哈希值。

使用步骤：

1. 在项目根目录创建 static 文件夹
2. 将图片放入 static/images 等子目录
3. 在Markdown或React组件中直接引用 /images/example.png

方案二：修改Webpack配置

对于必须通过Webpack处理的图片资源，可以通过自定义插件修改Webpack配置：

module.exports = {
  plugins: [
    function customImagePlugin(context, options) {
      return {
        name: 'custom-image-plugin',
        configureWebpack(config) {
          const imageRule = config.module.rules.find(
            (rule) => rule.test && rule.test.test('.png')
          );
          if (imageRule) {
            imageRule.use[0].options.name = 'assets/images/[name].[ext]';
          }
          return config;
        },
      };
    },
  ],
};

需要注意的是，直接修改Webpack配置可能会影响构建性能和缓存策略，建议仅在确实需要时使用此方法。

最佳实践建议

1. 对于需要固定URL的图片，优先使用static目录方案
2. 对于网站主要内容中的图片，保留默认的哈希机制以获得更好的性能
3. 如果必须修改Webpack配置，确保了解其对构建系统的影响
4. 在团队协作项目中，任何对构建配置的修改都应该明确记录原因

通过合理选择方案，开发者可以在Docusaurus项目中灵活地管理图片资源，既满足特定需求，又保持网站的整体性能。