文档使用说明（必读）

欢迎阅读 LayaAir3 引擎文档

在这里，您可以了解如何阅读与查找该文档，以及本地编辑与贡献文档。

1. 善用搜索功能

尽管我们尽力让文档目录结构清晰易查，但如果您只是想在遇到问题时快速找到答案，搜索功能 是最高效的方式。

例如，若您希望让 IDE 界面显示中文，可在搜索栏中输入 “中文界面”，即可获得相关结果。如图 1-1 所示：

（图 1-1）

点击搜索结果中的内容条目，可跳转到对应的文档，查看详细内容。

2. 选择正确的引擎版本文档

查看文档时，很多开发者会忽略 引擎版本 这一点。

LayaAir 引擎的不同版本（如 3.1、3.2、3.3、3.4……）会新增或修改一些功能，可能会导致使用方式不同。

请务必通过文档左上角的 版本号下拉菜单，选择与您当前使用版本一致的分支。

例如，若您使用的是 3.3.2 版本，应选择 3.3 分支 文档进行查看。如图 1-2 所示：

（图 1-2）

3. 自定义文档显示风格

点击文档右上角的 A 图标，即可打开 显示设置面板，在其中可调整：

• 字号大小
• 字体样式
• 背景主题

您可以根据喜好设置最舒适的阅读样式。如图 1-3 所示：

（图 1-3）

点击折叠图标，可以隐藏或展开文档导航栏。如图 1-4 所示：

（图 1-4）

4. 文档反馈与修改

LayaAir 文档是开源的，开发者可以：

• 本地克隆 文档查看、编辑或新增；
• 点击右上角Github图标，跳转文档对应的Github文档，提交修改；

📘 中文文档仓库：https://github.com/layabox/LayaAir-Doc-ZH

📘 英文文档仓库：https://github.com/layabox/LayaAir-Doc-EN

文档仓库中的不同分支与 引擎版本号 逐一对应。

如果您不熟悉 GitHub 的提交流程，也可直接联系官方客服反馈问题，我们会尽快进行修改。

为本站新增、修改文档的完整流程（建页、排版、嵌入引擎成品、在线编辑、上线检查）见本节后续各小节，无需另开独立页面。

💬 客服微信：LayaAir_Engine

（扫一扫添加官方客服微信）

---

4.1 文档写作与编辑指南

本文档系统基于 Astro + Starlight 搭建。导航、搜索、版本切换、明暗主题、无刷新翻页等外壳能力全部由框架统一提供，文档作者只需专注于正文内容。

本文介绍如何为本站撰写和编辑文档，涵盖建页、排版、嵌入富媒体（对比图、视频、引擎成品）、在线编辑，以及从写作到上线的完整流程。

4.2 五分钟跑通第一次编辑

npm install        # 仅首次需要
npm run dev        # 启动本地预览（自带在线编辑器）

浏览器打开终端提示的地址（通常是 http://localhost:4321/，端口被占用时会自动顺延到 4322），进入任意一篇文档，点击右下角的 「编辑本页」，在弹出的编辑框中修改内容，按 Ctrl+S 保存，正文即原地更新、页面不刷新。这是最快的上手路径，细节见后文各节。

4.3 文档的放置与命名

• 所有文档位于 src/content/docs/ 下，目录结构即 URL 结构。
• 扩展名 .md 或 .mdx 均可：纯文字用 .md；需要嵌入组件、横幅、交互演示时用 .mdx（本文即用 .mdx）。
• 每篇顶部 --- 之间的部分称为 frontmatter，用于声明页面元信息：

字段	必填	说明
title	是	页面标题，可用中文，但不要包含 Markdown 符号（#、*、反引号等）
description	是	一句话摘要，约 60–155 字，写入 <meta description>，用于搜索与 SEO
slug	强烈建议显式声明	页面 URL，规则见下方
draft	否	设为 true 表示未完成，不进目录，正式构建时不输出该页
banner	否	页面顶部横幅，见「4.5 MDX 扩展能力」

slug 命名规则（重要）

slug 只能包含 小写字母 a-z、数字 0-9、连字符 -、斜杠 /。

不要使用中文、空格、大写字母、点号。这类字符在 Windows 上看似正常，部署到 Linux 服务器后会导致断链 404，是本项目此前反复出现的问题。slug 应与文件路径保持一致，例如文件 unity-plugin/index.mdx 对应 slug "unity-plugin"。

4.4 正文写作（Markdown 基础）

• 标题层级：正文不要写 # H1（H1 由 title 自动生成）。从 ## H2 开始，逐级递进，不要跳级。

• 代码块：三个反引号加小写语言名，如 typescript、javascript、bash。

• 图片：图片文件放在 public/<与文档同名的目录>/img/，正文中使用相对当前文件的路径引用，构建时自动转换为站内绝对路径，并自动添加懒加载与点击放大：

  ![描述文字](./img/scene-after.svg)

  不要使用外链热链图片。页内编辑器粘贴图片时会自动按此约定写入（见 4.6 节）。渲染效果如下：

  

• 表格：使用标准 Markdown 表格即可，全站已统一为撑满、居中的样式。

• 外链：直接写 [文字](https://...)，会自动新标签打开并附带 ↗ 图标。

提示框（aside） 使用 Starlight 语法，共四种：

note —— 普通说明

用于补充信息、旁注。

tip —— 小技巧

用于提示窍门或推荐做法。

caution —— 注意

用于提醒容易出错之处。

danger —— 高风险

用于破坏性操作、已失效内容、会导致问题的写法。

写法是将内容置于 :::类型[可选标题] 与 ::: 之间。以上四个提示框均为实时渲染效果，非截图。

4.5 MDX 扩展能力

.mdx 相比 .md 多出两项能力：frontmatter 横幅 与 可复用组件。组件既包含排版件，也包含富媒体（对比滑块、视频、引擎成品嵌入）。

4.5.1 顶部横幅 banner

在 frontmatter 中加入 banner，页面顶部会显示一条醒目横幅，常用于标记内容过时：

banner:
  content: "⚠️ 本篇内容已过时，正在重写，请勿参照本篇代码开发。"

4.5.2 排版组件：能力对照表

在正文开头 import 后即可像标签一样使用。import 路径按文件层级计算：位于二级目录（如 docs/guides/xxx.mdx）的页面统一使用 ../../../components/，也建议将文档统一放在该层级以便记忆。现有组件如下：

完整 基本完整映射 部分 有损 / 子集 看配置 取决于开关 实验性 未完善 不支持 不导出

组件	import	用途	说明
FeatureTable	../../../components/FeatureTable.astro	完整	能力对照徽章表。传入 rows：每项 { feat, target, level, note }，level 取值为 full / part / conf / exp / no；note 支持内联 HTML。本表即由它渲染
ImageCompare	../../../components/ImageCompare.astro	完整	前后对比滑块，拖动手柄查看差异。传入 before / after 两张图与左右标签，见 4.5.3
VideoEmbed	../../../components/VideoEmbed.astro	完整	视频嵌入，支持本地 mp4、B 站、YouTube，见 4.5.4
EngineEmbed	../../../components/EngineEmbed.astro	完整	将 LayaAir 项目的网页发布产物（小场景 / 小游戏）以 iframe 嵌入文档，点击后加载，见 4.5.5

FeatureTable 的 level 对应五档支持度徽章（full 完整 / part 部分 / conf 看配置 / exp 实验 / no 不支持），图例由组件自带。

4.5.3 前后对比滑块 · ImageCompare

将两张图叠放，中间为可拖动的手柄，左右各有标签，适合展示优化前后、烘焙前后、改版前后的对比。拖动下方手柄即可查看（也支持键盘 ← → 微调）：

无光照 烘焙后

import ImageCompare from '../../../components/ImageCompare.astro';

<ImageCompare
  before="/guides/img/scene-before.svg"   {/* 手柄左侧露出的图 */}
  after="/guides/img/scene-after.svg"      {/* 手柄右侧露出的图 */}
  beforeLabel="无光照" afterLabel="烘焙后"
  start={50} />

两张图放在 public/guides/img/ 下，使用绝对路径引用（组件 prop 不经过相对路径的自动转换）。两张图的尺寸比例应保持一致。

4.5.4 视频嵌入 · VideoEmbed

三选一：本地或直链 mp4、B 站 BV号、YouTube id。平台视频采用点击后加载的方式，不点击则不连接第三方，可减少首屏负担并保护隐私。下方为 B 站方式的示例（点击封面加载）：

LayaAir 视频演示

import VideoEmbed from '../../../components/VideoEmbed.astro';

{/* 本地 / 直链 mp4 */}
<VideoEmbed src="/guides/img/my-clip.mp4" poster="/guides/img/cover.jpg" />

{/* B 站：填入 BV 号 */}
<VideoEmbed bilibili="BV1xx411c7XX" title="LayaAir 官方教程" />

{/* YouTube：填入视频 id */}
<VideoEmbed youtube="dQw4w9WgXcQ" title="Intro" />

自录教程存放于 public/guides/img/ 并用 src 引用；平台视频填入编号即可。

4.5.5 嵌入引擎成品 · EngineEmbed

文档中的可交互演示，应嵌入真实的 LayaAir 网页发布产物。在 LayaAir 中完成一个小场景或小游戏后，将其发布为网页版（得到含 index.html 的 web 目录），放入 public/ 下，即可用一行组件嵌入文档。组件默认只显示封面与「运行」按钮，点击后才加载引擎运行时——引擎运行时体积较大，采用按需加载，避免进入页面即占用资源，一页放置多个也不会卡顿。

下方为一个真实 LayaAir 项目在文档中运行，点击「运行」加载，右下角可全屏或在新窗口打开：

▶ 运行「LayaProject3 示例场景」 点击加载引擎运行时

🎮 LayaProject3 示例场景 ⛶ 全屏 ↗ 新窗口

import EngineEmbed from '../../../components/EngineEmbed.astro';

<EngineEmbed
  src="/guides/demos/laya-sample/index.html"   {/* 发布产物入口 */}
  title="我的小场景"
  ratio="16 / 9" />        {/* 竖屏项目可传 "3 / 4"，或用 height="480px" 固定高度 */}

落地步骤：

1. 在 IDE 中将项目发布为网页版，得到 release/web/（含 index.html、libs/、js/ 与资源，均为相对路径引用，整包移动后仍可运行）。
2. 将整个目录拷贝到 public/guides/demos/<项目名>/。
3. 组件 src 指向 /guides/demos/<项目名>/index.html。

引擎产物体积较大

一个发布产物通常有十几到二十几 MB，放入 public/ 会增大仓库与构建产物的体积。若不希望资源进入仓库，也可将产物托管到外部（CDN、对象存储），组件 src 直接填写外链 URL 即可。

4.5.6 框架自动提供的能力

完整 基本完整映射 部分 有损 / 子集 看配置 取决于开关 实验性 未完善 不支持 不导出

能力	触发方式	状态	说明
图片懒加载	自动	完整	正文图片自动添加 loading=lazy，按需加载
点击放大灯箱	自动	完整	正文图片点击后放大查看
外链新标签 + ↗	自动	完整	站外链接自动新窗口打开、附带安全 rel
中文分词搜索	自动	完整	Pagefind 全站搜索，支持中文
版本切换 / 明暗主题	自动	完整	侧栏顶部 3.0–3.4 下拉、右上角切换主题

以上均为框架自动提供，写作时无需额外处理。

4.6 在线编辑

npm run dev 模式下，每篇文档右下角有 「编辑本页」 与 「编辑目录」 两个按钮。该编辑器仅存在于本地预览，npm run build 的正式产物中没有任何残留。

4.6.1 编辑本页

点击「编辑本页」，右侧滑出 Markdown 面板，输入即实时预览（仅重绘变化的段落），Ctrl+S 保存且页面不刷新。

编辑处与预览处双向定位：双击或划选编辑框中的文字，预览区会自动滚动到对应位置并高亮，便于在长文中快速找到正文的对应处。

粘贴图片自动编号：在编辑框中直接 Ctrl+V 粘贴截图或拖入图片文件，图片会自动上传到本页 img/ 目录、按顺序编号命名，并在光标处插入相对路径引用（如 ./img/1.png）。若先选中一条已有的图片引用再粘贴，则为换图（原地覆盖，可撤回）。

4.6.2 编辑目录

点击「编辑目录」，将侧边导航作为缩进文本树编辑——Tab / Shift+Tab 调整层级，Alt+↑/↓ 移动行，改名、调序、增删条目均直接编辑文本，Ctrl+S 写回 src/sidebar.generated.json。

在此新建文档：加入一行 - [新页面](/分类/新页面/) 并保存，目标页面不存在时会自动生成骨架文件（含 draft: true 与占位正文）。

刷新后即可看到新建的草稿页，点击「编辑本页」撰写正文；完成后删除 frontmatter 中的 draft: true（并补上 description）即可上线。草稿状态下页面标注为「内容整理中」，不会进入正式构建。

4.6.3 其它

换图撤回、垃圾回收、定位规则等更多细节见 dev-editor/README.md。也可使用 VS Code、Cursor、Typora 等外部编辑器直接修改文件，dev 会热更新。

4.7 从建页到上线

1. 建页：

   • 新页（演示页、专题页等）→ 直接编写 .mdx，遵循 4.3 至 4.5 节的规范。
   • 存量页（来自旧文档）→ 通过 migrate.mjs 重建，不要手写，否则会被覆盖。

2. 写作中：未完成的页在 frontmatter 设 draft: true，不进目录、不上线；完成后删除该行（并补全 description）即自动上线。

3. 进入侧栏：目录数据位于 src/sidebar.generated.json。最便捷的方式是使用 4.6.2 节的「编辑目录」直接添加条目；也可修改 migrate.mjs 后重新生成。

4. 交付前验证（三项均需通过）：

   npm run build          # 构建并补充懒加载，必须无报错
   node audit-links.mjs   # 断链审计，必须输出 0
   npm run preview        # 查看正式构建的实际效果

交付时提供可验证的结果

修改过 CSS 或样式后，提醒对方 Ctrl+Shift+R 强制刷新（浏览器缓存旧 CSS 是常见的误报来源）。交付时提供可访问的地址，必要时附截图。

4.8 常见问题

• slug / 链接断链：中文、大写、空格、点号、下划线出现在 slug 或站内链接中，会导致 Windows 正常而 Linux 404。站内链接统一小写、结尾带 /。
• 图片不显示：图片需放在 public/<目录>/img/，正文用 ./img/xxx.png 相对路径引用；本地预览图片显示异常时，运行一次 npm run link:images。
• 组件图片路径：ImageCompare、EngineEmbed 等组件 prop 中的路径需使用绝对路径（/guides/...），不经过 Markdown 的相对转绝对处理。
• 行尾符：本项目 frontmatter 为 LF、正文为 CRLF 的混合行尾，部分编辑器保存时会改动整段行尾符，导致 diff 中出现大量无实质内容的改动。提交前应检查，只保留真实改动。
• 提示框类型：仅 note / tip / caution / danger 四种。

---