本地预览与提交前检查

AI 辅助编写说明

本文初稿以及其中文和英文译文均为在AI辅助下完成的。如果发现有任何错误，欢迎通过此页面进行反馈，或是在GitHub上提交修改建议。

本站基于 Docusaurus，使用 yarn 管理依赖。改完文档后，请先在本地跑通预览与检查，再提交 Pull Request。

一、环境准备

1. Git 与源码仓库

预览与提交前检查都会读取仓库的 Git 历史记录，因此必须使用 Git，并且必须克隆源码仓库，而不是下载源码 ZIP 解压运行——解压得到的只是普通目录，没有 .git 历史，预览与检查命令会因此失败。

1. 安装 Git，并确认命令可用：

git --version

2. 克隆源码仓库并进入目录：

git clone https://github.com/lumina-layer-studio/Lumina-Studio-Wiki.git
cd Lumina-Studio-Wiki

2. Node.js 与 Corepack

需要 Node.js 20 或更高版本，以及 Corepack。Corepack 随 Node.js 的 14.19.0 至 25.0.0 之前的版本一起分发；从 Node.js 25 版本开始，不会再附带 Corepack。

若系统提示找不到 corepack（例如使用 Node.js 25 或更高版本），需要先手动安装用户态 Corepack，步骤见 Corepack 官方安装说明：

npm install -g corepack

否则直接使用随 Node.js 分发的 Corepack：

corepack enable

再安装项目依赖：

yarn install --immutable

项目固定使用 package.json 中声明的 Yarn 4 版本。

二、本地预览

yarn start 默认只预览中文：

yarn start

英文预览需要显式指定语言：

yarn start --locale en

中文与英文是两套独立的构建，但两条默认命令使用同一个端口，所以一次只能运行一种语言的预览：切换语言时先用 Ctrl+C 停止当前预览，再启动另一条命令。

三、提交前检查

依次执行：

yarn typecheck
yarn build

四、目录与文件约定

• 中文正文位于 docs/，英文正文位于 i18n/en/docusaurus-plugin-content-docs/current/。
• 每篇教程使用独立目录，MDX 文件与目录同名，图片放在页面目录内的 assets/ 中。

示例：

docs/tutorials/example/example.mdx
docs/tutorials/example/assets/step-01.webp

五、写法约定

• 该文档仅使用 Docusaurus 官方提供的 Markdown/MDX 功能，不允许在正文中引入自定义图片组件或路径相关组件。
• MDX 正文中不写 import 语句。
• 图片使用页面目录下的相对路径写法：

<img src={require('./assets/step-01.webp').default} alt="步骤一" />

• 贡献与规范细节见 CONTRIBUTING.md。

六、AI 辅助说明

本页初稿与中英翻译在 AI 辅助下完成，命令、版本与路径已在提交前逐条核对；AI 参与方式与反馈渠道见文章开头的说明。

参与贡献

欢迎通过 Issue 或 Pull Request 来修正文案内容、补充相关教程以及改进翻译质量；详细规则请参见 CONTRIBUTING.md。