migrate: Next.js 16 → Astro 7

.gitattributes

@@ -1,2 +1,25 @@
 # Auto detect text files and perform LF normalization
 * text=auto
+
+# 统一以 LF 存入仓库、LF 检出到工作区（跨平台一致，避免每个提交都出现
+# "LF will be replaced by CRLF" 噪音，也避免 Windows 上产生整文件 diff）
+* text=auto eol=lf
+
+# 锁死行尾的产物/配置：这些文件由工具生成或本身就是纯文本数据，
+# 不允许 git 做任何 eol 转换，否则内容会随平台漂移
+pnpm-lock.yaml   text eol=lf
+dist/**          text eol=lf
+public/CNAME     text eol=lf
+public/robots.txt text eol=lf
+*.mdx            text eol=lf
+*.md             text eol=lf
+
+# 二进制资源：禁止任何行尾/文本转换
+*.png  binary
+*.gif  binary
+*.jpg  binary
+*.jpeg binary
+*.webp binary
+*.ico  binary
+*.woff  binary
+*.woff2 binary

.github/workflows/ci.yml

@@ -20,14 +20,18 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@v5
 
-      - name: Use Node.js LTS
+      - name: Use Node.js 24
         uses: actions/setup-node@v6
         with:
-          node-version: lts/*
+          node-version: 24
           check-latest: true
           cache: pnpm
 
+      - name: Install dependencies
+        run: pnpm install
+
       - name: Build project
-        run: |
-          pnpm install
-          pnpm build
+        run: pnpm build
+
+      - name: Type check
+        run: pnpm check

.github/workflows/deploy.yml

@@ -29,25 +29,19 @@ jobs:
 
       - name: Configure GitHub Pages
         uses: actions/configure-pages@v5
+        with:
+          static_site_generator: astro
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v5
 
-      - name: Use Node.js LTS
+      - name: Use Node.js 24
         uses: actions/setup-node@v6
         with:
-          node-version: lts/*
+          node-version: 24
           check-latest: true
           cache: pnpm
 
-      - name: Setup Next.js cache
-        uses: actions/cache@v5
-        with:
-          path: .next/cache
-          key: ${{ runner.os }}-nextjs-${{ hashFiles('**/pnpm-lock.yaml') }}
-          restore-keys: |
-            ${{ runner.os }}-nextjs-
-
       - name: Install dependencies
         run: pnpm install
 
@@ -56,12 +50,12 @@ jobs:
 
       - name: Add CNAME
         run: |
-          echo "mx-space.js.org" > out/CNAME
+          echo "mx-space.js.org" > dist/CNAME
 
       - name: Upload GitHub Pages artifact
         uses: actions/upload-pages-artifact@v4
         with:
-          path: out
+          path: dist
 
   deploy:
     runs-on: ubuntu-latest

.gitignore

@@ -1,43 +1,41 @@
-# deps
-/node_modules
-
-# generated content
-.contentlayer
-.content-collections
-.source
-
-# test & build
-/coverage
-/.next/
-/out/
-/build
+# 依赖
+node_modules/
+.pnpm-store/
+
+# 构建产物与工具缓存
+dist/
+.astro/
 *.tsbuildinfo
 
-# misc
-.DS_Store
-*.pem
-/.pnp
-.pnp.js
+# 测试覆盖率（本项目未接入测试，仅作兜底）
+coverage/
+
+# 构建时生成的数据（prebuild 会自动写入，缺失会导致构建失败）
+src/components/contributors.json
+
+# 环境变量
+.env
+.env.*
+!.env.example
+
+# 编辑器与 IDE
+.vscode/*
+!.vscode/extensions.json
+.idea/
+
+# 日志
+*.log
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+pnpm-debug.log*
 
-# others
-.env*.local
-.vercel
-next-env.d.ts
-.env
-.vscode/
-
-# generated contributors data
-src/components/contributors.json
+# 证书
+*.pem
 
-# sitemap
-public/sitemap.xml
+# 系统文件
+.DS_Store
+Thumbs.db
 
-# Webstorm
-/.idea/.gitignore
-/.idea/docs.iml
-/.idea/MarsCodeWorkspaceAppSettings.xml
-/.idea/modules.xml
-/.idea/vcs.xml
+# Yarn PnP（本项目用 pnpm，留作兜底）
+.pnp.*

README.md

@@ -2,14 +2,16 @@
 
 ## Contributing 贡献
 
-这个站点使用的是 [Fumadocs](https://fumadocs.vercel.app) 程序。站点内容使用 MDX 编写，文档文件在 `/content/docs` 文件夹中。如果只有一些简单的修改，你可以直接在 GitHub 网页端进行修改并新建一个 Pull Request.
+这个站点基于 [Astro](https://astro.build) + [Fumadocs](https://fumadocs.vercel.app) 构建，样式使用 Tailwind CSS 4，输出为纯静态站点（`dist/`）。站点内容使用 MDX 编写，文档文件在仓库根目录的 `content/docs/` 文件夹中（内容目录保持在仓库根的 `content/docs/`，不随 Astro 迁移移动）。如果只有一些简单的修改，你可以直接在 GitHub 网页端进行修改并新建一个 Pull Request.
 
-在本地开发中，[pnpm](https://pnpm.io) 被选用为项目的包管理器，你需要使用 pnpm 安装依赖：
+在本地开发中，[pnpm](https://pnpm.io) 被选用为项目的包管理器，需要 Node.js ≥ 22.12.0（推荐 24）。你需要使用 pnpm 安装依赖：
 
 ```bash
   pnpm install
-  pnpm dev
-  pnpm build
+  pnpm dev       # astro dev，本地开发服务器
+  pnpm check     # astro check，类型检查
+  pnpm build     # astro build，产物输出到 dist/
+  pnpm preview   # astro preview，本地预览构建产物
 ```
 
 ## Working on the content 修改文字

astro.config.mjs

@@ -0,0 +1,104 @@
+import { fileURLToPath } from 'node:url';
+import mdx from '@astrojs/mdx';
+import react from '@astrojs/react';
+import { unified } from '@astrojs/markdown-remark';
+import tailwindcss from '@tailwindcss/vite';
+import { defineConfig } from 'astro/config';
+import {
+  rehypeCode,
+  remarkCodeTab,
+  remarkHeading,
+  remarkNpm,
+  remarkStructure,
+} from 'fumadocs-core/mdx-plugins';
+import { remarkSteps } from 'fumadocs-core/mdx-plugins/remark-steps';
+import { redirects } from './redirects.config.mjs';
+
+/**
+ * 把 content/docs 里对 fumadocs 组件的导入重定向到 Astro 兼容层。
+ * 两个兼容层解决的问题不同，详见各自的源文件：
+ * - `fumadocs-ui/components/card`      → src/components/card.tsx（JSX 作为 prop 传入 React 组件）
+ * - `fumadocs-ui/components/accordion` → src/components/accordion.tsx（Radix Context 跨不出 Astro slot）
+ *
+ * 为什么用「按 importer 路径限定」的 resolveId 插件，而不是全局 alias：
+ * 兼容层自己也要导入真正的 fumadocs 组件，全局 alias 会让它解析到自己（循环）。
+ * 限定 importer 后，兼容层自身（src/components/**）与其它 consumer 都不受影响，
+ * content/docs 也因此无需改动（保持“内容零搬迁”）。
+ */
+function astroReactCompat() {
+  const shims = new Map([
+    ['fumadocs-ui/components/card', fileURLToPath(new URL('./src/components/card.tsx', import.meta.url))],
+    [
+      'fumadocs-ui/components/accordion',
+      fileURLToPath(new URL('./src/components/accordion.tsx', import.meta.url)),
+    ],
+  ]);
+
+  return {
+    name: 'mx:astro-react-compat',
+    enforce: 'pre',
+    resolveId(source, importer) {
+      if (!importer || !/[\\/]content[\\/]docs[\\/]/.test(importer)) return null;
+
+      return shims.get(source) ?? null;
+    },
+  };
+}
+
+// Astro 7 默认使用自研的 Sätteri Markdown 管线，fumadocs 的 remark/rehype 插件
+// 只有在显式设置 `markdown.processor: unified()` 时才会生效。
+export default defineConfig({
+  site: 'https://mx-space.js.org',
+  output: 'static',
+  // Astro 7 的默认值是 'jsx'，会按 JSX 规则吃掉行内元素之间的空白；
+  // 本站大量中英混排，先保持 v6 行为。
+  compressHTML: true,
+  redirects,
+  markdown: {
+    processor: unified({
+      syntaxHighlight: false,
+      remarkPlugins: [
+        remarkHeading,
+        remarkCodeTab,
+        remarkNpm,
+        [remarkStructure, { exportAs: 'structuredData' }],
+        remarkSteps,
+      ],
+      rehypePlugins: [rehypeCode],
+    }),
+  },
+  integrations: [
+    react(),
+    mdx({
+      extendMarkdownConfig: true,
+      syntaxHighlight: false,
+    }),
+    // 不使用 @astrojs/sitemap：它只产出 /sitemap-index.xml + /sitemap-0.xml，
+    // 会让旧站既有的 /sitemap.xml 消失。改由 src/pages/sitemap.xml.ts 手写端点，
+    // 保持 URL 与条数与旧站一致。
+  ],
+  vite: {
+    plugins: [astroReactCompat(), tailwindcss()],
+    build: {
+      rollupOptions: {
+        // Astro 7 的 content-assets 插件会为**每个 MDX**生成一个虚拟模块
+        // `<file>.mdx?astroPropagatedAssets`，其注入源码里硬编码了一行
+        // `"use astro:head-inject";`（见 astro/dist/content/vite-plugin-content-assets.js:103-112）。
+        // rolldown 对 bundler 注入的 module-level 指令会打 MODULE_LEVEL_DIRECTIVE 警告，
+        // 本站 53 个 MDX 页面 = 53 条，全部指向这个虚拟模块，与我们写的代码无关，
+        // 也没有开关可以关掉（该字符串在 Astro 源码里是字面量）。
+        // 这里按「警告 code + 虚拟模块 id」双重精确过滤，其余任何警告照常输出，
+        // 以保证“构建零警告”这条验收仍然有判别力。
+        onwarn(warning, defaultHandler) {
+          const where = `${warning.id ?? ''} ${warning.message ?? ''}`;
+
+          if (warning.code === 'MODULE_LEVEL_DIRECTIVE' && where.includes('astroPropagatedAssets')) {
+            return;
+          }
+
+          defaultHandler(warning);
+        },
+      },
+    },
+  },
+});

cli.json

@@ -9,6 +9,6 @@
   },
   "baseDir": "src",
   "uiLibrary": "radix-ui",
-  "framework": "next",
+  "framework": "astro",
   "commands": {}
 }

content/docs/deploy/docker.mdx

@@ -3,6 +3,9 @@ title: Docker 部署
 description: 通过 Docker 部署 Mix-Space 的后端
 ---
 
+import { EnvVariableConfig } from '@/components/env-variable-config'
+import { TypeTable } from 'fumadocs-ui/components/type-table'
+
 ## 安装 Docker [step]
 
 不论在海外还是中国大陆境内我们都可以使用 Linuxmirrors 提供的 Docker 安装脚本来安装 Docker 和 Docker Compose，它具备可在多种系统上安装 Docker 的能力：
@@ -68,6 +71,7 @@ wget "https://gh-proxy.org/https://github.com/mx-space/core/blob/master/docker-c
 在下方的组件中填入配置，点击复制后粘贴到 `docker-compose.yml` 的 `environment` 字段中，覆盖`JWT_SECRET` 和 `ALLOWED_ORIGINS` 的值，如果需要开启加密功能，请添加并将 `ENCRYPT_ENABLE` 的值改为 `true`，并填入 `ENCRYPT_KEY`。
 
 <EnvVariableConfig
+  client:load
   format="yaml"
   variableNames={[
     {
@@ -89,11 +93,10 @@ wget "https://gh-proxy.org/https://github.com/mx-space/core/blob/master/docker-c
   ]}
 />
 
-import { TypeTable } from 'fumadocs-ui/components/type-table';
-
 ### 变量介绍
 
 <TypeTable
+  client:load
   type={{
     'JWT 密钥': {
       description: '长度 16-32 个字符，用于加密用户 JWT，务必保存好不要泄露。',

content/docs/index.mdx

@@ -3,6 +3,8 @@ title: Mix Space 简介
 description: 为个人博客、创作者主页打造的 AI 驱动型内容管理系统
 ---
 
+import { File, Folder } from 'fumadocs-ui/components/files'
+
 ![UwU Logo](/images/uwu.png)
 
 这个 uwu 标志由 [Arthals](https://github.com/zhuozhiyongde) 设计。
@@ -15,13 +17,13 @@ Mix Space 是一个简洁、现代、高性能的个人博客系统，采用前
 
 Mix Space 由两大部分组成：
 
-<Folder name="Mix Space" defaultOpen>
-  <Folder name="后端 (Core)">
+<Folder name="Mix Space" defaultOpen client:load>
+  <Folder name="后端 (Core)" client:load>
     <File name="RESTful API" />
     <File name="后台管理系统 (qAqDmin)" />
     <File name="数据库 (PostgreSQL)" />
   </Folder>
-  <Folder name="前端 (Theme)">
+  <Folder name="前端 (Theme)" client:load>
     <File name="访客展示页面" />
     <File name="主题配置" />
   </Folder>

content/docs/themes/community/cyber.mdx

@@ -3,7 +3,7 @@ title: Cyber
 description: Shiro 的分支, 以炫酷赛博风为核心开发目标
 ---
 
-import Image from 'next/image'
+import { Image } from '@/components/image'
 
 <ToGithub repo="At87668/Cyber" description="Cyber — A cyber style theme for Mx Space." />
 ## 概述