这个项目交付了什么
这是独立的静态文档站。构建后全部文件位于 dist/，不需要服务器函数、数据库、Worker、账号凭据或游戏服务端在线。站内全文搜索、事件筛选与代码复制在浏览器本地完成，不向游戏管理接口发送请求。
文档针对 Go 服务端 dnf/v1，核对日期 2026-10-26，源码快照 cda08ef。当前稳定事件 63 个、业务 Hook 6 项。网站成功发布不代表游戏实例已更新到该版本；使用插件前应通过实例自己的 /local/plugins/catalog 核对实际能力。
本地构建与预览
先安装 Node.js 20 或更新的受支持版本，以及配套 npm。项目的 .node-version 推荐 Node.js 22.22.2。首次下载项目后，在项目根目录运行：
npm ci
npm run check
npm run preview
打开终端显示的 http://localhost:4173。check 会先生产构建，再检查全部页面、内部链接、锚点、事件数据结构、示例清单/权限和下载文件。预览命令也会先构建一次，仅监听本机。
开发时使用 npm run dev。修改 content/、data/、public/ 或 src/ 后自动重新生成页面，浏览器手动刷新即可。修改构建脚本或页面元数据时重新启动开发命令。端口冲突时可在命令进程中设置 PORT 环境变量。
只生成部署文件：
npm run build
Cloudflare Pages：连接 Git 仓库
将本项目作为独立仓库交给部署者。仓库根目录包含 package.json，不要把 dist/ 当作源码仓库根。
- 在 Cloudflare 控制台打开 Workers & Pages，创建 Pages 项目并连接仓库。控制台文案可能随版本变化，选择静态 Pages 构建流程。
- 框架预设选择 None。构建命令设为
npm run build，构建输出目录设为dist，根目录为项目根目录。 - 配置生产分支，并在构建环境设置
NODE_VERSION=22.22.2。构建器应先安装锁文件指定的依赖。 - 部署成功后，在 Pages 提供的域名验证首页、
/quickstart/、事件搜索与 ZIP 下载。
| 设置项 | 值 |
|---|---|
| 项目类型 | Cloudflare Pages，静态站点 |
| 框架预设 | None |
| 构建命令 | npm run build |
| 输出目录 | dist |
| Node.js | 22.22.2 |
| 服务端函数 / 绑定 / 数据库 | 不需要 |
站内使用从 / 开始的绝对路径，适用于独立域名或 Pages 子域名的根目录。部署到其他站点的子路径前，需要统一调整构建器和前端中的资源及路由前缀。
Cloudflare Pages：直接上传
如果不连接 Git，先执行生产构建，再在 Pages 的直接上传流程上传 dist/ 的内容。首页应直接是 index.html，不能再嵌套一层 dist/。
也可在已获得部署权限的终端使用 Wrangler。项目中的 wrangler.jsonc 已指定 Pages 输出目录，项目名默认 dnf90-lua-docs；项目名被占用时，先修改为自己账户下可用的名称。
npm ci
npm run check
npx --yes wrangler@4 login
npx --yes wrangler@4 pages project create dnf90-lua-docs --production-branch main --force
npx --yes wrangler@4 pages deploy dist --project-name dnf90-lua-docs --branch main
创建项目只需执行一次；已有同名项目时跳过创建。新版 Wrangler 可能把新建项目转交给 Workers，首次创建时的 --force 明确使用独立 Pages 项目；后续向这个项目执行 pages deploy 不加此参数。login 使用部署者自己的账户授权。自动化部署可以使用 Cloudflare 官方支持的环境变量凭据，但不要放进文档内容、Lua 框架、wrangler.jsonc 或提交记录。
本项目没有自动执行发布的 npm 脚本。构建与验证可以离线进行，上传需要部署者主动执行部署命令。
验收发布结果
- 首页与
/api/可直接打开，刷新深层页面仍返回正确文档。 - 事件目录显示
63 / 63；搜索shop_purchased、切换领域、展开字段可用。 - 按
Ctrl K或 macOS 的⌘ K打开全文搜索，查找inventory.item_use能跳到对应章节。 - 可以复制代码，下载 完整示例 ZIP、编辑器声明 和 事件 JSON。
- 手机端可打开导航，表格与代码块可横向滚动，正文不超出屏幕。
- 访问不存在的路径时显示自定义 404，而不是把首页当作所有路径的响应。
build-info.json 记录 API、核对的服务端提交与事件数量，可用于核对上传的文档版本。public/_headers 提供同源资源策略及静态安全响应头，构建后自动放入输出根目录；不要从输出中遗漏它。
维护文档与接口快照
| 目录 / 文件 | 用途 |
|---|---|
content/*.md |
指南、API、Hook 与运维正文 |
data/events.json |
每个事件的名称、字段、时机、边界和示例 |
data/site.json |
页面导航、API 与源码核对版本 |
public/downloads/examples/ |
用户实际下载运行的插件文件 |
public/downloads/dnf.lua |
仅供编辑器使用的声明，不由服务端加载 |
src/site.css、src/site.js |
自适应页面、搜索、筛选和复制交互 |
scripts/build.mjs |
Markdown 生成器、搜索索引、事件卡片与 ZIP 构建 |
站点构建不依赖服务端仓库，因此可以单独交付。源码变更后，维护者应同步阅读真实契约与适配入口，更新正文、事件 JSON、示例和编辑器声明，再更新核对版本。不要仅因目录名称相同就推断语义不变。
当机器上有对应服务端源码时，可以补充运行：
npm run verify:source -- ../dnf-source
这个只读检查对比稳定事件名称、Hook 名称和源文件 SHA-256，帮助发现快照漂移。它不会替代字段、事务边界和真实入口的代码审查。
浏览器回归可在安装 Chromium 后运行：
npx playwright install chromium
npm run test:browser
该脚本会启动临时本机预览，检查桌面与手机视口、全文搜索、事件筛选、深链、复制、下载和导航。浏览器不需要游戏服务端。
其他静态托管
任何能以 dist/ 为根目录的静态服务器都可以托管。保留目录中的 index.html 路由、自定义 404.html、资源与下载文件，并根据对应托管平台配置安全响应头。Cloudflare 的 _headers 只由支持该格式的平台解析，其他服务器需配置等效响应头。
文档站与游戏服务端是两个独立的交付物。玩家不需要安装这个网站；服主按照 快速开始 把插件放入游戏发行包的顶层 runtime/plugins/。