07 · 持久化与部署

数据流概览

db/data/bookmarks.ts（源数据）→ 构建写入 Astro DB → 导航页 entry.astro 序列化 JSON → React 渲染。管理端「保存」即将草稿写回 bookmarks.ts。

开发环境持久化

1. 启动 vpr dev 或 vpr dev:all。
2. 访问 /bookmarks/admin/ 并完成认证。
3. 执行 保存；成功则更新 db/data/bookmarks.ts。
4. 刷新 /bookmarks/nav/ 验证（dev 热更新或重建数据）。

持久化经书签 Dev API（integrations/bookmarks-admin.ts 注册的 /admin/api/*），无需手动调用 HTTP 客户端。

生产部署流程

1. 本地编辑并持久化 → bookmarks.ts 产生 diff
2. git add / commit / push
3. CI 或 vpr build 部署

生产站点无写入 bookmarks.ts 能力；勿依赖 GitHub Pages 上的保存按钮更新线上数据。

构建验证

vpr build

通过即表示 seed 与 injectRoute 正常。书签路由由 integration 注册，不经过 src/pages/。

站点图标与构建

vpr build 前会执行 generate:bookmark-logos 更新 bookmark-logos.json；线上需配置 PUBLIC_LOGO_DEV_TOKEN。见 06 · 书签站点图标。

主题子系统

管理端顶栏与导航页共用主题定制器，偏好键为 wwlight:*。见 主题定制器与用户偏好。

故障排查

现象	可能原因
保存 403 / 失败	生产环境，或 dev 未挂载 API
导航页数据陈旧	未持久化、未 commit，或 CDN 缓存
认证失败	凭据与 .env 不一致，或未重启 dev

API 与脚本细节以 src/bookmarks/README.md 为准。