build(fix): 添加构建后处理脚本以支持 clean URLs

Author: kqcoxn

package.json

@@ -11,8 +11,8 @@
   },
   "scripts": {
     "dev": "vitepress dev src",
-    "build": "vitepress build src",
-    "preview": "vitepress build src && vitepress preview src"
+    "build": "vitepress build src && node scripts/post-build.js",
+    "preview": "vitepress build src && node scripts/post-build.js && vitepress preview src"
   },
   "dependencies": {
     "shiki": "^3.18.0"

scripts/post-build.js

@@ -0,0 +1,58 @@
+import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync } from "fs";
+import { join, dirname, basename, extname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const distDir = join(__dirname, "..", "src", ".vitepress", "dist");
+
+// 递归处理所有 HTML 文件，为 cleanUrls 创建目录结构
+function createCleanUrlStructure(dir) {
+  const files = readdirSync(dir);
+
+  for (const file of files) {
+    const fullPath = join(dir, file);
+    const stat = statSync(fullPath);
+
+    if (stat.isDirectory()) {
+      createCleanUrlStructure(fullPath);
+    } else if (
+      file.endsWith(".html") &&
+      file !== "index.html" &&
+      file !== "404.html" &&
+      file !== "200.html"
+    ) {
+      // 例如: docs/1.1-QuickStarted.html -> docs/1.1-QuickStarted/index.html
+      const nameWithoutExt = basename(file, ".html");
+      const targetDir = join(dir, nameWithoutExt);
+
+      if (!existsSync(targetDir)) {
+        mkdirSync(targetDir, { recursive: true });
+      }
+
+      const targetFile = join(targetDir, "index.html");
+      copyFileSync(fullPath, targetFile);
+      console.log(`✓ Created ${targetFile}`);
+    }
+  }
+}
+
+// 创建 SPA fallback
+const indexHtml = join(distDir, "index.html");
+const fallback200 = join(distDir, "200.html");
+const fallback404 = join(distDir, "404.html");
+
+if (existsSync(indexHtml)) {
+  copyFileSync(indexHtml, fallback200);
+  console.log("✓ Created 200.html for SPA fallback");
+}
+
+if (existsSync(fallback404)) {
+  // 404.html 指向 index.html 的内容以支持 SPA 路由
+  copyFileSync(indexHtml, fallback404);
+  console.log("✓ Updated 404.html for SPA fallback");
+}
+
+// 为 cleanUrls 创建目录结构
+console.log("\nCreating clean URL directory structure...");
+createCleanUrlStructure(distDir);
+console.log("\n✓ Build post-processing complete!");

src/.vitepress/config.mts

@@ -78,8 +78,8 @@ export default withMermaid({
     const enPath = isEn
       ? routePath
       : routePath.startsWith("/en/")
-      ? routePath
-      : "/en" + routePath;
+        ? routePath
+        : "/en" + routePath;
     const zhUrl = hostname + baseNoSlash + zhPath;
     const enUrl = hostname + baseNoSlash + enPath;
 

src/.vitepress/sidebars.ts

@@ -8,8 +8,11 @@ export function genSidebar(args: VitePressSidebarOptions = {}) {
   });
 }
 
-function processRewritesRecursion(routes, targetKV) {
-  const rewrites = {};
+function processRewritesRecursion(
+  routes: Array<any>,
+  targetKV: Record<string, string>,
+) {
+  const rewrites: Record<string, string> = {};
   routes.forEach((route) => {
     let link = route.link as string;
     let text = route.text as string;
@@ -31,7 +34,7 @@ function processRewritesRecursion(routes, targetKV) {
   return rewrites;
 }
 
-function processRoutes(routes) {
+function processRoutes(routes: Array<any>) {
   routes.forEach((route) => {
     if (route["items"]) {
       processRoutes(route["items"]);
@@ -47,7 +50,7 @@ function processRoutes(routes) {
 }
 
 function getFileNameKV(routes: Array<any>) {
-  const kv = {};
+  const kv: Record<string, string> = {};
   routes.forEach((route) => {
     if (route.items) {
       Object.assign(kv, getFileNameKV(route.items));
@@ -66,7 +69,7 @@ function getLocaleSidebars() {
 
   // 生成国际化路径重写
   const rewriteList = [zn_routes];
-  const rewrites = {};
+  const rewrites: Record<string, string> = {};
   const kv = getFileNameKV(en_routes);
   rewriteList.forEach((item) => {
     const rw = processRewritesRecursion(item, kv);