Fix images (#6)

cuisongliu · web-flow · commit 2429bf402e23 · 2026-01-20T23:14:51.000+08:00
* Support runtime domain for MDX images and update related documentation

* Enhance MdxImage component to support non-string src types and improve image source resolution

* Support direct serving of images from the /content route with path validation
diff --git a/app/content/[...path]/route.ts b/app/content/[...path]/route.ts
@@ -0,0 +1,48 @@
+import { NextResponse } from 'next/server';
+import { readFile } from 'fs/promises';
+import path from 'path';
+
+export const runtime = 'nodejs';
+
+const CONTENT_ROOT = path.resolve(process.cwd(), 'content');
+const MIME_TYPES: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+};
+
+const isSafePath = (filePath: string) =>
+  filePath === CONTENT_ROOT || filePath.startsWith(`${CONTENT_ROOT}${path.sep}`);
+
+export async function GET(
+  request: Request,
+  { params }: { params: { path?: string[] } },
+) {
+  const segments = params.path ?? [];
+  const filePath = path.resolve(CONTENT_ROOT, ...segments);
+  if (!isSafePath(filePath)) {
+    return new NextResponse('Not Found', { status: 404 });
+  }
+
+  const extension = path.extname(filePath).toLowerCase();
+  const contentType = MIME_TYPES[extension];
+  if (!contentType) {
+    return new NextResponse('Not Found', { status: 404 });
+  }
+
+  try {
+    const data = await readFile(filePath);
+    return new NextResponse(data, {
+      status: 200,
+      headers: {
+        'Content-Type': contentType,
+        'Cache-Control': 'public, max-age=31536000, immutable',
+      },
+    });
+  } catch {
+    return new NextResponse('Not Found', { status: 404 });
+  }
+}
diff --git a/components/mdx/mdx-image.tsx b/components/mdx/mdx-image.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { ImageZoom } from 'fumadocs-ui/components/image-zoom';
-import { useMemo } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
 
 const CDN_PATTERN = /^https?:\/\/images\.sealos\.run/;
 const APP_URL_PLACEHOLDER = '__APP_URL__';
@@ -56,15 +56,35 @@ const resolveImageSrc = (src: MdxImageSrc) => {
 };
 
 export function MdxImage(props: React.ImgHTMLAttributes<HTMLImageElement>) {
-  const { className, src, ...rest } = props;
+  const { className, src, onError, ...rest } = props;
   const resolvedSrc = useMemo(() => resolveImageSrc(src), [src]);
+  const [currentSrc, setCurrentSrc] = useState<MdxImageSrc>(resolvedSrc);
+  const [didFallback, setDidFallback] = useState(false);
+  const originalSrcRef = useRef<MdxImageSrc>(src);
+  const resolvedSrcRef = useRef<MdxImageSrc>(resolvedSrc);
   const mergedClassName = ['rounded-xl', className].filter(Boolean).join(' ');
 
+  useEffect(() => {
+    originalSrcRef.current = src;
+    resolvedSrcRef.current = resolvedSrc;
+    setCurrentSrc(resolvedSrc);
+    setDidFallback(false);
+  }, [src, resolvedSrc]);
+
+  const handleError: React.ReactEventHandler<HTMLImageElement> = (event) => {
+    onError?.(event);
+    if (didFallback) return;
+    if (resolvedSrcRef.current === originalSrcRef.current) return;
+    setDidFallback(true);
+    setCurrentSrc(originalSrcRef.current);
+  };
+
   return (
     <ImageZoom
       {...(rest as any)}
-      src={resolvedSrc}
+      src={currentSrc}
       className={mergedClassName}
+      onError={handleError}
     />
   );
 }
diff --git a/helloagents/CHANGELOG.md b/helloagents/CHANGELOG.md
@@ -11,6 +11,7 @@
 - 新增 Sealos Hub 镜像上传文档
 - 新增 PR 预览环境工作流
 - 支持 MDX 图片运行时域名
+- 支持 content 图片直出
 
 ### 变更
 - 初始化知识库（helloagents）
diff --git a/helloagents/history/2026-01/202601202306_content-image-route/task.md b/helloagents/history/2026-01/202601202306_content-image-route/task.md
@@ -0,0 +1,20 @@
+# 任务清单: content 图片直出
+
+目录: `helloagents/plan/202601202306_content-image-route/`
+
+---
+
+## 1. 服务端路由
+- [√] 1.1 在 `app/content/[...path]/route.ts` 中实现 content 图片直出（仅允许图片扩展名，防止路径穿越）
+- [√] 1.2 更新 `middleware.ts` 放行 `/content/` 路由避免被 i18n 重写
+
+## 2. 构建脚本
+- [√] 2.1 更新 `scripts/replace-image-paths.sh` 将 `./images` 替换为 `/content/.../images`
+
+## 3. 文档同步
+- [√] 3.1 更新 `helloagents/wiki/modules/app.md` 记录 content 图片直出规范
+- [√] 3.2 更新 `helloagents/CHANGELOG.md` 记录改动
+- [√] 3.3 更新 `helloagents/history/index.md` 增加历史索引
+
+## 4. 校验
+- [√] 4.1 访问本地 `/content/...` 图片地址验证返回 `image/*`
diff --git a/helloagents/history/index.md b/helloagents/history/index.md
@@ -8,6 +8,7 @@
 
 | 时间戳 | 功能名称 | 类型 | 状态 | 方案包路径 |
 |--------|----------|------|------|------------|
+| 202601202306 | content 图片直出 | 功能 | ✅已完成 | [链接](2026-01/202601202306_content-image-route/) |
 | 202601202148 | MDX 图片运行时域名 | 功能 | ✅已完成 | [链接](2026-01/202601202148_mdx-image-runtime-base/) |
 | 202601201758 | Sealos Hub 镜像上传文档 | 文档 | ✅已完成 | [链接](2026-01/202601201758_sealos-hub-image-upload-doc/) |
 | 202601201726 | AI Proxy 渠道配置文档 | 文档 | ✅已完成 | [链接](2026-01/202601201726_aiproxy-channel-doc/) |
@@ -21,6 +22,7 @@
 
 ### 2026-01
 
+- [202601202306_content-image-route](2026-01/202601202306_content-image-route/) - content 图片直出
 - [202601202148_mdx-image-runtime-base](2026-01/202601202148_mdx-image-runtime-base/) - MDX 图片运行时域名
 - [202601201927_pr-preview-workflow](2026-01/202601201927_pr-preview-workflow/) - PR 预览环境工作流
 - [202601201758_sealos-hub-image-upload-doc](2026-01/202601201758_sealos-hub-image-upload-doc/) - Sealos Hub 镜像上传文档
diff --git a/helloagents/wiki/modules/app.md b/helloagents/wiki/modules/app.md
@@ -28,6 +28,15 @@
 - 图片可随部署域名切换
 - 保持 ImageZoom 交互体验
 
+### 需求: content 图片直出
+**模块:** app
+提供 `/content/*` 路由直接读取仓库 `content/` 目录中的图片资源。
+
+#### 场景: 文档图片直出
+图片请求可通过 `/content/...` 访问到 `content/` 内的图片文件。
+- 限制仅允许图片扩展名
+- 防止路径穿越
+
 ## API接口
 暂无
 
@@ -42,3 +51,4 @@
 
 ## 变更历史
 - [202601202148_mdx-image-runtime-base](../../history/2026-01/202601202148_mdx-image-runtime-base/) - 支持 MDX 图片运行时域名
+- [202601202306_content-image-route](../../history/2026-01/202601202306_content-image-route/) - 支持 content 图片直出
diff --git a/helloagents/wiki/modules/components.md b/helloagents/wiki/modules/components.md
@@ -27,6 +27,7 @@
 在渲染时替换 MDX 图片地址为当前部署域名。
 - 兼容现有 CDN 图片地址
 - 兼容非字符串 src（如静态导入）
+- 替换失败时回退至原始地址
 - 保持图片圆角样式
 
 ## API接口
diff --git a/middleware.ts b/middleware.ts
@@ -53,6 +53,6 @@ export async function middleware(request: NextRequest, event: NextFetchEvent) {
 
 export const config = {
   matcher: [
-    '/((?!api|_next/static|_next/image|images/|icons/|favicon/|favicon.ico|logo.svg|Deploy-on-Sealos.svg|sitemap.xml|llms.txt|rss.xml|ai-faqs\..*\.json).*)/',
+    '/((?!api|_next/static|_next/image|content/|images/|icons/|favicon/|favicon.ico|logo.svg|Deploy-on-Sealos.svg|sitemap.xml|llms.txt|rss.xml|ai-faqs\..*\.json).*)/',
   ],
 };
diff --git a/scripts/replace-image-paths.sh b/scripts/replace-image-paths.sh
@@ -6,10 +6,10 @@ find content -type f \( -name "*.mdx" -o -name "*.md" \) | while read -r file; d
     # Get the directory path relative to project root
     dir=$(dirname "$file")
     
-    # Replace "](./images" with CDN URL + absolute path
-    sed -i "s#](\./images#](https://images.sealos.run/gh/labring/sealos.io@main/${dir}/images#g" "$file"
+    # Replace "](./images" with local content path for in-app serving
+    sed -i "s#](\./images#](/content/${dir}/images#g" "$file"
     
     echo "Processed: $file"
 done
 
-echo "Image path replacement completed"
+echo "Image path replacement completed"
