Merge pull request #195 from InvolutionHell/codex/improve-fumadocs-debugging-performance

Improve Fumadocs dev experience when offline

Author: longsizhuo

README.md

@@ -60,6 +60,14 @@ pnpm dev
 
 打开浏览器访问 [http://localhost:3000](http://localhost:3000)。
 
+> 本地离线调试 Fumadocs 时，如果发现界面加载需要等待远程图片尺寸请求，可以设置环境变量 `DOCS_REMOTE_IMAGE_SIZE=disable` 或直接沿用默认行为（开发模式自动禁用远程图片尺寸请求），显著加快调试速度。如需强制启用远程图片尺寸补全，可手动设置 `DOCS_REMOTE_IMAGE_SIZE=force`。
+
+| `DOCS_REMOTE_IMAGE_SIZE` | 行为说明                                                                         |
+| ------------------------ | -------------------------------------------------------------------------------- |
+| 未设置（默认）           | 构建时忽略远程图片尺寸请求报错，开发模式下额外禁用远程尺寸请求，避免离线调试受阻 |
+| `disable`                | 在任何模式下都跳过远程图片尺寸请求，仅使用文档内手动声明的宽高                   |
+| `force`                  | 强制启用远程图片尺寸请求，并在出现错误时抛出异常以暴露问题                       |
+
 > Windows + VSCode(Cursor) 可能触发 Husky 提交钩子问题，建议直接使用命令行执行 `git commit`。
 
 更多安装脚本、调试命令与常见问题，请查看 [CONTRIBUTING.md](CONTRIBUTING.md)。

source.config.ts

@@ -7,10 +7,21 @@ export const docs = defineDocs({
 });
 
 // 默认改为忽略拉取远程图片尺寸时的网络错误，既不中断构建，也能在可访问时自动补全宽高。
-const imageOptions =
-  process.env.DOCS_REMOTE_IMAGE_SIZE === "force"
-    ? undefined
-    : { onError: "ignore" as const };
+// 另外，在开发模式下禁用远程图片尺寸的主动请求，避免本地离线调试时等待网络超时。
+const remoteImageMode = process.env.DOCS_REMOTE_IMAGE_SIZE;
+const shouldForceRemote = remoteImageMode === "force";
+const shouldDisableRemote =
+  remoteImageMode === "disable" ||
+  (!shouldForceRemote && process.env.NODE_ENV === "development");
+
+// shouldDisableRemote 为 true 时，Fumadocs 不会再访问远程地址获取尺寸，
+// 而是只依赖手动在文档里声明的宽高或保持未知尺寸，避免在离线或网络较慢时拖慢开发调试。
+const imageOptions = shouldForceRemote
+  ? undefined
+  : {
+      onError: "ignore" as const,
+      ...(shouldDisableRemote && { external: false as const }),
+    };
 
 export default defineConfig({
   mdxOptions: {