docs: add troubleshooting tip for @rspress/core/theme-original export errors in migration guide (#2984)

SoonIter · web-flow · commit 18f9b18ca0ca · 2026-01-09T07:12:41.000Z
diff --git a/website/docs/en/guide/migration/rspress-v1.mdx b/website/docs/en/guide/migration/rspress-v1.mdx
@@ -163,6 +163,20 @@ If using the `@theme` alias, add path mapping in `tsconfig.json` for type hints:
 }
 ```
 
+:::tip
+
+If you encounter errors about missing exports from `@theme` or `@rspress/core/theme`, it's likely because you didn't use `@rspress/core/theme-original` when overriding the theme in the theme folder, causing a circular reference:
+
+```txt
+× ESModulesLinkingError: export 'SvgWrapper' (imported as 'SvgWrapper') was not found in '@theme' (possible exports: HomeLayout, Layout, Search, Tag, getCustomMDXComponent)
+
+× ESModulesLinkingError: export 'Banner' (imported as 'Banner') was not found in '@rspress/core/theme' (possible exports: HomeLayout, Layout, Search, Tag, getCustomMDXComponent)
+```
+
+Make sure to use `@rspress/core/theme-original` in the `theme` folder and correctly export all components.
+
+:::
+
 ## [Important] Shiki code highlighting replaces prism
 
 Rspress V2 uses Shiki v3 for code highlighting by default. Prism has been removed.
diff --git a/website/docs/zh/guide/migration/rspress-v1.mdx b/website/docs/zh/guide/migration/rspress-v1.mdx
@@ -163,6 +163,20 @@ import { PackageManagerTabs } from '@theme';
 }
 ```
 
+:::tip
+
+如果你遇到 `@theme` 或 `@rspress/core/theme` 缺少导出的报错，大概率是因为 theme 文件夹下覆盖主题时没有使用 `@rspress/core/theme-original`，造成循环引用：
+
+```txt
+× ESModulesLinkingError: export 'SvgWrapper' (imported as 'SvgWrapper') was not found in '@theme' (possible exports: HomeLayout, Layout, Search, Tag, getCustomMDXComponent)
+
+× ESModulesLinkingError: export 'Banner' (imported as 'Banner') was not found in '@rspress/core/theme' (possible exports: HomeLayout, Layout, Search, Tag, getCustomMDXComponent)
+```
+
+请确保在 `theme` 文件夹中使用 `@rspress/core/theme-original` 并正确导出所有组件。
+
+:::
+
 ## [重要] Shiki 代码高亮替代 prism
 
 Rspress V2 默认使用 Shiki v3 进行代码高亮，Prism 已被移除。
