feat: add detailed documentation on development issues encountered in Spring Lament Blog, including SSR hydration errors, large file imports, and Mermaid chart rendering optimizations

Author: zhaoshiwei1

docs/开发问题记录.md

@@ -0,0 +1,197 @@
+# Spring Lament Blog 开发问题记录
+
+## 1. 文章详情页水合不匹配
+
+### 问题描述
+
+Next.js SSR 水合错误：服务端渲染的 HTML 与客户端渲染不匹配，导致控制台出现 hydration 错误。
+
+### 错误信息
+
+```
+Hydration failed because the server rendered HTML didn't match the client
+Error: Text content does not match server-rendered HTML.
+```
+
+### 问题原因
+
+- 标题 ID 生成使用了 `Date.now()` 和 `Math.random()`
+- 服务端和客户端生成的随机值不同
+- 导致相同内容生成不同的 DOM 结构
+
+### 解决方案
+
+1. **实现稳定的哈希算法**：
+
+   ```javascript
+   const generateStableUniqueId = (text: string, index: number) => {
+     const baseId = text.toLowerCase().replace(/[^\w\u4e00-\u9fa5\s-]/g, "").replace(/\s+/g, "-");
+     const hash = text.split('').reduce((a, b) => {
+       a = ((a << 5) - a) + b.charCodeAt(0);
+       return a & a;
+     }, 0);
+     return `${baseId}-${Math.abs(hash).toString(36)}-${index}`;
+   };
+   ```
+
+2. **预生成所有标题 ID**：在 useMemo 中一次性解析所有标题并生成稳定的 ID 映射
+
+3. **统一 Mermaid ID 生成**：使用内容哈希而非随机数
+
+### 验证结果
+
+- ✅ SSR 水合错误完全消除
+- ✅ 服务端客户端 ID 生成一致
+- ✅ 目录跳转功能正常
+
+---
+
+## 2. 导入导出文件太大
+
+### 问题描述
+
+应用打包后文件体积过大，影响加载性能。
+
+### 待分析
+
+- Bundle 分析
+- 代码分割优化
+- 依赖项瘦身
+
+---
+
+## 3. Mermaid重绘导致的页面闪烁
+
+### 问题描述
+
+在博客文章页面滚动时，Mermaid 图表出现明显的重渲染闪烁现象，严重影响用户体验。
+
+### 复现步骤
+
+1. 访问包含 Mermaid 图表的文章页面
+2. 向下滚动页面
+3. 观察到 Mermaid 图表频繁闪烁/重新渲染
+
+### 问题根因分析
+
+1. **组件频繁重渲染**：滚动时 `activeHeading` 状态频繁更新 → 整个 MarkdownRenderer 组件重新渲染
+2. **Mermaid 重新初始化**：每次组件重渲染时，Mermaid 图表都会重新渲染
+3. **资源浪费**：主题检测的 MutationObserver 被重复创建
+
+### 解决方案
+
+#### 3.1 Mermaid组件优化 (`src/components/markdown/mermaid.tsx`)
+
+**添加全局缓存机制**：
+
+```typescript
+// 全局缓存已渲染的图表
+const mermaidCache = new Map<string, { svg: string; theme: string }>();
+```
+
+**优化主题检测**：
+
+```typescript
+// 只在组件挂载时创建一次 MutationObserver
+useEffect(() => {
+  setIsDark(currentTheme === "dark");
+
+  const checkTheme = () => {
+    const newIsDark = document.documentElement.classList.contains("dark");
+    setIsDark(newIsDark);
+  };
+
+  const observer = new MutationObserver(checkTheme);
+  observer.observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ["class"],
+  });
+
+  return () => observer.disconnect();
+}, []); // 只在挂载时执行一次
+```
+
+**渲染防抖机制**：
+
+```typescript
+const renderAttempted = useRef(false);
+
+const renderChart = async () => {
+  if (!chart || renderAttempted.current) return;
+
+  const theme = isDark ? "dark" : "default";
+  const cacheKey = `${chart}-${theme}`;
+
+  // 检查缓存
+  const cached = mermaidCache.get(cacheKey);
+  if (cached) {
+    setSvg(cached.svg);
+    setError("");
+    return;
+  }
+
+  renderAttempted.current = true;
+  // ... 渲染逻辑
+  // 存入缓存
+  mermaidCache.set(cacheKey, { svg: renderedSvg, theme });
+};
+```
+
+#### 3.2 MarkdownRenderer组件优化 (`src/components/markdown/markdown-renderer.tsx`)
+
+**使用 useMemo 防止不必要的重渲染**：
+
+```typescript
+{useMemo(
+  () => (
+    <ReactMarkdown
+      remarkPlugins={[remarkGfm]}
+      rehypePlugins={[rehypeRaw]}
+      components={{...}}
+    >
+      {content || ""}
+    </ReactMarkdown>
+  ),
+  [content, headingIdMap]  // 只依赖 content 和 headingIdMap
+)}
+```
+
+### 性能提升效果
+
+**优化前**：
+
+- ❌ 滚动时 Mermaid 图表频繁闪烁
+- ❌ 每次滚动都重新渲染整个 Markdown 内容
+- ❌ 重复创建 MutationObserver 和事件监听器
+
+**优化后**：
+
+- ✅ 滚动时 Mermaid 图表保持稳定
+- ✅ 缓存机制大幅提升渲染性能
+- ✅ 资源复用，减少内存占用
+- ✅ 用户体验显著改善
+
+### 关键经验总结
+
+1. **识别并分离频繁变化的状态**：将滚动相关状态与内容渲染分离
+2. **为昂贵的渲染操作实现缓存**：避免重复的异步渲染
+3. **合理管理副作用的生命周期**：确保资源正确清理
+4. **使用 React 优化手段**：useMemo、useCallback 等
+
+---
+
+## 开发经验总结
+
+### 性能优化原则
+
+1. 优先识别性能瓶颈，避免过度优化
+2. 合理使用缓存机制
+3. 注意 React 渲染优化
+4. 监控内存使用情况
+
+### 调试技巧
+
+1. 使用 React DevTools 分析组件渲染
+2. 利用浏览器性能面板定位问题
+3. 添加适当的日志和断点
+4. 重视用户反馈和实际体验