构建、部署与更新

默认静态模式将网站生成到 dist/public。确认内容状态和发布日期后，构建并检查该目录，再上传到静态托管服务。

本地检查与构建

在模板根目录执行：

1pnpm check2pnpm test3pnpm build4pnpm preview

check 会检查字段、引用与类型。test 验证内容和服务规则。build 使用 Astro 输出完整页面，收集附件、建立 Pagefind 索引，并检查实际产物链接。只有全部成功才替换 dist，失败不会覆盖上一成功版本。

preview 默认监听本机 4321，读取已有产物。若仍有 dev 占用端口，先在对应终端停止它。

发布目录

默认 static 模式只发布 dist/public 中的内容。其中包含页面、浏览器资源、正文附件、分页辅助数据、全文索引、RSS 和站点地图，应作为同一版本一起上传。

不要只拷贝首页，也不要把 dist 父目录、知识源、开发缓存或运行凭据作为公开目录。静态托管需要支持目录地址读取 index.html，例如 /articles/source/ 对应该目录的页面。

上传 GitHub 的是已提交源码；对外网站使用的是构建产物。当前模板自带的工作流负责检查，没有自动部署步骤。选择托管方式后，再按对应平台配置发布位置和 HTTPS。

根路径与子路径

在 site.config.ts 中设置自己的 site。部署根路径使用 base: '/'；部署在 /blog/ 时使用 base: '/blog/'，并让文件实际位于该路径。

1site: 'https://your-domain.example',2base: '/blog/',

保留其他配置，重新构建再查看页面与资源地址。路径问题常表现为首页可开、图片或搜索不可用，不要用逐页硬编码绝对地址来补救。

搜索与分页一起更新

Pagefind 在构建时读取允许的正文。增加文章后，重新构建才能获得新全文索引。文章列表的字段搜索与全站全文搜索范围不同：前者查询标题、摘要、标签和专题名，后者查询已索引的正文。

默认列表按页生成；分类和关键词筛选才按需读取当前栏目的检索数据、当前页卡片。部署时包含 listing、pagefind 和相关脚本，不混用不同构建版本。

替换示例内容

先写自己的正文，再调整首页 home.featured 和 home.recent，然后修改专题和书籍 YAML。删除示例前搜索其 ID，清理正文链接、关联阅读和集合引用，最后再删除无需保留的附件。

可以移除整套示例，但应保留自己的有效内容关系。不要为了使构建通过，随意把缺少发布状态的文件改成公开；先明确它应该是草稿、私人、预览还是公开。

可选站主服务

需要完整私人阅读时，将 clarislet.config.ts 的 mode 改为 owner，或者设置 CLARISLET_MODE=owner 后构建。此时会生成 public 和 owner 两个目标。

凭据通过 pnpm owner:password 工具设置，用户名、密码与会话密钥使用服务端环境变量，具体要求见工程的 docs/deployment.md。这里不提供可直接复用的默认密码。启动本项目 Node 服务进行统一认证，不能使用普通静态托管公开整个 dist。

恢复 static 时清理相应环境设置，再构建并重启预览服务，使它读取新的 manifest。SQLite 只保存会话，正文继续由 Markdown 维护。

发布检查清单

• 核对日期、发布状态和公开范围，确认标题与摘要可以公开。
• 打开首页、文章末页、代表性正文和资料目录，检查图片、附件和永久链接。
• 搜索新增文章，确认匿名访问找不到私人或草稿正文。
• 从正文返回列表，确认页码、筛选和滚动位置恢复。
• 在手机宽度和明暗主题下检查表格、代码和导航。
• 发布同一次构建的 dist/public 内容，包括页面、附件和索引。

如果启用了站主服务，再分别用匿名、登录和退出后的会话检查全文、附件与索引的访问结果。