Docusaurus国际化(i18n)中相对图片路径的优化方案问询

核心需求回顾 #

不想将图片重复复制到每个i18n/<lang>子目录，同时希望图片继续与引用它的Markdown文件就近存放，替代方案如下：

方案一：自定义组件重写资源解析逻辑 #

通过替换默认的@theme/IdealImage组件，让它自动加载原docs目录下的图片，无需复制。

1. 创建自定义组件
   在项目src/components/CustomIdealImage.js中编写：

import IdealImage from '@theme/IdealImage';
import React from 'react';

export default function CustomIdealImage({ img, ...props }) {
  // 从国际化路径中剥离出原docs的资源路径
  const originalSrc = img?.src?.replace(
    /^\/i18n\/[^\/]+\/docusaurus-plugin-content-docs\/current/,
    '/docs'
  );
  // 优先使用原路径资源，无匹配则 fallback 到默认逻辑
  const resolvedImg = originalSrc ? { src: originalSrc } : img;
  return <IdealImage img={resolvedImg} {...props} />;
}

2. 配置组件替换
   在docusaurus.config.js中添加Webpack别名，让默认的@theme/IdealImage指向自定义组件：

const path = require('path');

module.exports = {
  // ...其他配置
  webpack: {
    alias: {
      '@theme/IdealImage': path.resolve(__dirname, 'src/components/CustomIdealImage.js'),
    },
  },
};

之后所有MDX中引用的<IdealImage>都会自动加载原docs目录的图片。

方案二：用软链接替代文件复制 #

通过创建符号链接（软链接），让i18n目录下的_shared文件夹直接指向原docs目录的对应文件夹，既保持就近结构，又避免重复存储。

• Linux/macOS：

# 示例：为中文本地化目录创建getting-started的_shared链接
ln -s ../../../../../../docs/01-getting-started/_shared i18n/zh/docusaurus-plugin-content-docs/current/01-getting-started/_shared

• Windows（管理员权限）：

# 示例：为中文本地化目录创建getting-started的_shared链接
mklink /D i18n\zh\docusaurus-plugin-content-docs\current\01-getting-started\_shared ..\..\..\..\..\docs\01-getting-started\_shared

可以编写脚本批量创建所有目录的软链接，避免手动操作。

方案三：配置文档插件的资源解析规则 #

修改@docusaurus/plugin-content-docs的配置，让国际化文档能直接访问原docs目录的静态资源：

在docusaurus.config.js中调整插件配置：

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'default',
        path: 'docs',
        routeBasePath: 'docs',
        // 让国际化文档可以访问原docs的静态资源
        staticAssetsPath: '../docs',
        // 可选：自动替换MDX中的图片路径为原docs路径
        parseFrontMatter: async (params) => {
          params.content = params.content.replace(
            /!\[.*?\]\(\.\/_shared\/(.*?)\)/g,
            '![$1](/docs/$2/_shared/$1)'
          );
          return params;
        },
      },
    ],
  ],
};

此方案适合纯Markdown图片引用（![alt](./_shared/xxx.png)），如果用组件引用则需结合方案一。

关于直接读取原docs图片的可行性 #

完全可以实现，方案一就是通过自定义组件直接改写资源路径，让IdealImage加载原docs目录的图片；也可以通过Webpack的资源解析规则，让Docusaurus在处理国际化文档的图片引用时，直接指向原docs目录的文件。

内容的提问来源于stack exchange，提问作者Petr Broz