构建与发布

VitePress 将 Markdown 和主题编译为静态页面。线上由 Web 服务器直接提供文件，不需要常驻 Node.js 应用。

在线发布

日常写作可直接使用 文档工作台：编辑文档或目录，保存草稿，然后点击“发布更新”。后台会生成新版本，通过检查后切换前台，失败时保留当前版本。

文档草稿保存在服务器 /opt/alanco-wiki/workspace/，已发布版本位于 /opt/alanco-wiki/releases/，编辑历史位于 /opt/alanco-wiki/editor-data/history/。使用在线工作台后，这份工作区是后续发布的内容来源，手工发布时需要先同步它，避免覆盖新增文档。

本地预览

安装 Node.js 20 或更新版本，然后在项目根目录执行：

npm ci
npm run dev

终端会显示本地预览地址。编辑 Markdown 或主题后，开发服务器会更新页面。

生成生产文件

npm run build

生成目录为 docs/.vitepress/dist/。构建时会检查站内链接，并生成全文搜索索引。

npm run preview

发布前使用预览命令检查首页、文档、搜索和移动端菜单。

发布新版本

1. 保存源文件并生成生产文件。
2. 将构建目录上传到新的版本目录。
3. 检查 HTML、图片和静态资源是否完整。
4. 切换 Web 服务器使用的版本目录。
5. 验证首页、文档深层链接、搜索与 404 页面。

保留上一个版本

使用独立版本目录发布，出现问题时可以切换回上一版本，而不必重新构建。

独立域名

本文档站计划使用 wiki.rainside.top，当前按独立端口提供服务。完成域名解析后，还需要在入口 Web 服务器或 CDN 中配置对应站点与 HTTPS 证书。

DNS 记录只负责将域名指向服务器，不能直接指定网页使用的端口。若希望通过不带端口的域名访问，需要配置 80 / 443 入口转发。

缓存

带内容哈希的 CSS 和 JavaScript 可以长期缓存；HTML 使用较短缓存或重新验证，确保发布后能获取新的资源地址。

更新依赖

依赖版本由 package-lock.json 固定。升级 VitePress 后重新构建，并检查自定义主题与默认主题结构是否仍然兼容。