1. 系统更新与基础工具#

在开始之前，确保您的 Arch Linux 系统是最新的，并安装必要的构建工具。

1
sudo pacman -Syu
2
sudo pacman -S --needed base-devel git curl unzip

2. 安装 运行时环境#

Docusaurus 基于 React，需要 Node.js 环境。虽然可以使用 pacman 安装，但为了获得更好的版本控制和性能，推荐使用 Bun（一个极速的 JavaScript 运行时，兼容 npm 生态且安装更简单）。

1
# 使用官方脚本安装 Bun
2
curl -fsSL https://bun.sh/install | bash
3
sudo pacman -S bun
4

5
# 加载环境变量 (根据提示添加到 ~/.bashrc 或 ~/.zshrc)
6
source ~/.bashrc
7
# 或 source ~/.zshrc
8

9
# 验证安装
10
bun --version

1
# 通过 pacman 安装 Node.js (可能版本稍旧，但稳定)
2
sudo pacman -S nodejs npm
3

4
# 或者使用 nvm/fnm 管理版本
5
curl -fsSL https://fnm.vercel.app/install | bash
6
source ~/.bashrc
7
fnm use --install-if-missing 20 # 安装 Node.js 20 LTS

3. 安装 PlantUML 及 Java 环境#

本项目架构图大量使用 PlantUML (.puml 文件)。Docusaurus 本身不直接支持 .puml 渲染，我们需要在本地安装 PlantUML 以便：

1. 在 VS Code 中预览。
2. (可选) 编写脚本在构建时将 .puml 转换为图片。

Arch Linux 的安装非常简便：

1
# 安装 JRE (PlantUML 依赖 Java)
2
sudo pacman -S jre-openjdk
3

4
# 安装 PlantUML
5
sudo pacman -S plantuml
6

7
# 验证安装
8
plantuml -version

💡 提示：安装完成后，建议在 VS Code 中安装 “PlantUML” 插件，并配置 plantuml.jar 路径（通常 pacman 安装的可以直接识别，若不行需手动指定 jar 路径）。

4. 项目初始化与依赖安装#

假设您已经按照 Monorepo 结构创建了目录：

1
ATRI-Server/
2
├── docs/              # 文档源码
3
├── website/           # Docusaurus 站点

进入 website 目录并安装依赖：

1
cd website
2

3
# 如果使用 Bun (推荐)
4
bun install
5

6
# 如果使用 npm
7
npm install

5. 关键配置检查#

确保 website/docusaurus.config.ts 已正确指向根目录的 docs 文件夹（参考前文配置）：

1
presets: [
2
  ['classic', {
3
    docs: {
4
      path: '../docs', // 👈 关键点：指向外部 docs
5
      sidebarPath: './sidebars.ts',
6
      // ...
7
    },
8
  }],
9
],

同时，删除 website 目录下自动生成的 docs 和 blog 文件夹（如果不需要博客功能），避免路径冲突：

1
cd website
2
rm -rf docs blog

6. 启动开发服务器#

一切就绪后，启动本地开发服务器：

1
# 使用 Bun
2
bun run start
3

4
# 使用 npm
5
npm run start

浏览器将自动打开 http://localhost:3000。此时您应该能看到 ../docs 目录下的 Markdown 内容已被成功渲染。

Q1: PlantUML 图片如何在网站显示？#

Docusaurus 默认不支持直接解析 .puml 代码块。

• 短期方案：使用 VS Code 插件将 .puml 导出为 .png 或 .svg，放入 website/static/img/arch/，然后在 Markdown 中引用 ![架构图](/img/arch/design.png)。
• 长期方案：编写一个 Node.js 脚本，在 bun run build 之前遍历 ../docs，调用本地的 plantuml 命令批量生成图片到 website/static 目录。

Q2: 端口被占用怎么办？#

如果 3000 端口被占用，可以指定其他端口：

1
bun run start --port 3001

Q3: 热更新不生效？#

修改 docs 下的文件后，Docusaurus 通常会自动热重载。如果未生效，请检查 docusaurus.config.ts 中的 path 是否正确，或尝试重启服务。