feat(scripts): 新增本地 DocSearch 索引生成脚本，Mermaid 组件增加加载失败提示

- 新增 scripts/docsearch-index.mjs，支持从本地 dist 生成 Algolia 索引
- package.json 添加 docsearch:index 命令
- PERFORMANCE_NOTES.md 补充 Algolia 新应用配置和索引流程说明
- LazyMermaid.vue 增加 Mermaid 加载失败的错误处理和提示

Author: Snailclimb

PERFORMANCE_NOTES.md

@@ -92,6 +92,42 @@ cp "$VERIFY_FILE" "$SITE_DIR/"
   - `DOCSEARCH_INDEX_NAME`
 - 没有 DocSearch key 时关闭搜索，避免生成本地 `searchIndex.js`。
 - clean build 后已确认 `docs/.vuepress/.temp/internal/searchIndex.js` 不再生成。
+- Algolia 应用：
+  - 当前新应用 ID：`XXQ4GI90SC`
+  - 当前前端索引名：`javaguide`
+  - 当前前端 Search-Only API Key 已验证可用，掩码记录为：`3b514f...ef027b`
+- 官方 DocSearch Crawler 当前存在抽取不稳定问题：
+  - Crawler 能访问页面，但 UI 中 `recordExtractor` 没有稳定产出 records。
+  - 线上连续抓取还可能受 CDN/安全策略影响，导致部分页面拿不到完整正文。
+- 新增兜底索引脚本：`pnpm docsearch:index`
+  - 脚本位置：`scripts/docsearch-index.mjs`
+  - 推荐从本地构建产物 `dist` 生成索引，而不是在线抓取。
+  - 原因：`dist` 就是最终部署产物，索引内容和发布内容一致，也不会受 CDN/反爬/缓存影响。
+  - 推荐流程：
+
+```bash
+pnpm docs:build
+
+DOCSEARCH_APP_ID=XXQ4GI90SC \
+DOCSEARCH_INDEX_NAME=javaguide \
+DOCSEARCH_SOURCE_DIR=dist \
+DOCSEARCH_ADMIN_API_KEY=你的写入索引专用 Key \
+pnpm docsearch:index
+```
+
+- 注意：
+  - `DOCSEARCH_ADMIN_API_KEY` 只用于本地/CI 写索引，不能提交到仓库，不能放到前端环境变量里。
+  - 前端 `DOCSEARCH_API_KEY` 必须使用 `XXQ4GI90SC` 应用下的 Search-Only API Key，不能继续用旧应用 `U3RN7F5WI0` 的 key。
+  - 前端本地/部署构建环境变量示例：
+
+```bash
+DOCSEARCH_APP_ID=XXQ4GI90SC
+DOCSEARCH_INDEX_NAME=javaguide
+DOCSEARCH_API_KEY=3b514f...ef027b
+```
+
+- 上面的 `DOCSEARCH_API_KEY` 文档中只保留掩码；实际构建时使用完整 Search-Only API Key。
+- 2026-05-14 已用本地 `dist` 成功写入 `javaguide` 索引，索引 records 约 4.7 万条。
 
 ### GlobalUnlock
 

docs/.vuepress/components/LazyMermaid.vue

@@ -5,9 +5,14 @@
     :code="code"
     :title="title"
   />
-  <div v-else ref="placeholderEl" class="mermaid-lazy-placeholder">
-    <span class="mermaid-lazy-spinner" aria-hidden="true" />
-    <span>图表加载中</span>
+  <div
+    v-else
+    ref="placeholderEl"
+    class="mermaid-lazy-placeholder"
+    :class="{ 'is-error': loadError }"
+  >
+    <span v-if="!loadError" class="mermaid-lazy-spinner" aria-hidden="true" />
+    <span>{{ loadError ?? "图表加载中" }}</span>
   </div>
 </template>
 
@@ -23,16 +28,22 @@ defineProps<{
 const placeholderEl = shallowRef<HTMLElement | null>(null);
 const shouldRender = shallowRef(false);
 const MermaidComponent = shallowRef<Component | null>(null);
+const loadError = shallowRef<string | null>(null);
 let observer: IntersectionObserver | null = null;
 
 const loadMermaidComponent = async () => {
   if (MermaidComponent.value) return;
 
-  const { default: Mermaid } = await import(
-    /* @vite-ignore */
-    "@vuepress/plugin-markdown-chart/client/components/Mermaid.js"
-  );
-  MermaidComponent.value = markRaw(Mermaid);
+  try {
+    const { default: Mermaid } = await import(
+      "@vuepress/plugin-markdown-chart/client/components/Mermaid.js"
+    );
+    MermaidComponent.value = markRaw(Mermaid);
+    loadError.value = null;
+  } catch (error) {
+    console.error("Failed to load Mermaid component:", error);
+    loadError.value = "图表加载失败，请刷新重试";
+  }
 };
 
 const renderWhenVisible = () => {
@@ -78,6 +89,10 @@ onBeforeUnmount(() => {
   font-size: 0.9rem;
 }
 
+.mermaid-lazy-placeholder.is-error {
+  color: var(--vp-c-danger);
+}
+
 .mermaid-lazy-spinner {
   width: 1rem;
   height: 1rem;

package.json

@@ -28,6 +28,7 @@
     "docs:build:clean": "rm -rf docs/.vuepress/.temp docs/.vuepress/.cache && pnpm docs:build",
     "docs:dev": "vuepress dev docs",
     "docs:clean-dev": "vuepress dev docs --clean-cache",
+    "docsearch:index": "node scripts/docsearch-index.mjs",
     "lint": "pnpm lint:prettier && pnpm lint:md",
     "lint:md": "markdownlint-cli2 '**/*.md'",
     "lint:prettier": "prettier --check --write .",