本地运行与部署
这篇文档面向两类场景：
- 你第一次把 DomiVault 跑起来
- 你要排查“本地能跑 / 线上不能跑”的构建差异
环境要求
- 推荐：Node.js 22 LTS
- 最低：Node.js 18+
- 包管理器：bun 1.x
- 必备工具：Git
如果你主要在 Windows 上开发，建议配合：
第一次初始化
git clone <repo-url>
cd domivault
bun install
安装完成后，建议立即做一次类型检查：
bun x nuxi typecheck
本仓库统一使用
bun，不要混用npm、pnpm、yarn，避免锁文件和依赖树漂移。
开发模式
bun dev
默认地址：
- 页面：http://localhost:3000
- 首页摘要接口：http://localhost:3000/api/home/summary
- 文档摘要接口：http://localhost:3000/api/docs/summary
- 搜索索引接口：http://localhost:3000/api/docs/search-index
开发模式下的特点：
content/docs/*.md改动后会自动热更新- Nuxt 页面和 API 路由会一起重建
- 适合调试导航、搜索、文档内容和页面样式
如果 3000 端口被占用：
bun dev --port 3001
构建与预览
bun run build
bun run preview
build会生成生产环境产物，输出到dist/preview用来本地模拟生产包访问效果- 如果你要排查 Cloudflare Pages 问题，优先用
build而不是只跑dev
静态生成
bun run generate
适合纯静态导出场景；但本仓库包含服务端摘要与搜索接口，因此日常仍以 bun run build 为主。
与 Cloudflare Pages 保持一致
这个项目最终部署在 Cloudflare Pages。本地如果只跑 bun install + bun run build，有时还不够暴露平台差异。
建议在排查部署问题时，再补跑一次：
npm install --package-lock=false
bun x nuxi typecheck
bun run build
这样更容易提前发现：
npm install的 peer 依赖冲突- Nuxt Content / Nitro 在 CI 环境下的构建差异
- Cloudflare 安装链路和本地 bun 安装链路不一致的问题
修改文档时的建议流程
- 先补全 frontmatter：
title、description、date、category - 再写正文结构，至少保证有清晰的小节
- 添加站内互链，减少“孤立页面”
- 如有必要，补到 站内导航与索引
- 提交前重新构建，确认内容能进入产物
常见问题
依赖安装失败
- 先确认 Node 版本是否过低
- 再确认 bun 是否在 PATH 中
- 如果误生成了
package-lock.json或pnpm-lock.yaml，请删掉后重装
页面打不开
- 看终端是否真的启动成功
- 检查 3000 端口是否被别的程序占用
- 用
bun dev --port 3001换端口验证
文档改了但页面没刷新
- 确认修改的是
content/docs下的文件 - 观察终端是否出现内容重建日志
- 不行就重启
bun dev
本地构建通过，线上部署失败
优先复现：
npm install --package-lock=false
Cloudflare Pages 的安装阶段走的是 npm 解析链路，本地只用 bun 有时复现不出问题。
接口返回 404
- 先确认你跑的是
bun dev或bun run build - 如果你只用了
generate，部分服务端接口验证会失真
提交前检查
- 安装：
bun install - 类型：
bun x nuxi typecheck - 构建：
bun run build - 内容：frontmatter、站内互链、外链、表格格式