启动项目

使用哪种启动方式

首次排查建议使用完整的 本地预览流程。它使用构建产物，在 http://localhost:4400 提供公开站、登录、工作台和接口；邮件写入本地收件记录。文档使用 http://localhost:4406。

准备 Bun 1.4.2 或更新版本、Python 3 和独立 PostgreSQL 数据库。先复制 .env.example 为 .env.local，设置数据库地址、独立认证密钥及本地站点地址，再执行：

bun install --frozen-lockfile
bun run config:check
# 确认连接的是新建的隔离数据库后再迁移
bun db:migrate
bun build
bun run docs:build
bun run preview:start
bun run preview:status

启动器不会安装数据库。已有本机演示数据库和账号不属于复制新站的默认配置。

开发时热更新

bun dev

此方式并行启动公开站、工作台和接口开发服务，实际端口以终端输出为准。接口走 Wrangler 的本地代理，需要配置两条 Hyperdrive 本地连接变量；邮件使用真实 Resend，配置见 环境变量说明。不要把它和捕获邮件的完整预览流程混淆。

只改文档时可单独运行：

bun run docs:dev --host 127.0.0.1 --port 4406

若 4406 已由预览管理器占用，先停止该预览再启动开发服务。

常见问题

• 页面无法访问：检查 bun run preview:status，再看 .local 中对应服务日志，确认端口未被其他程序占用。
• 页面没有更新：预览读取构建产物。先重建，再停止并启动预览；文档预览同样需要重启。
• 接口提示缺表：检查 DATABASE_URL 目标及迁移记录，不要直接对未知数据库执行结构推送。
• 登录成功后跳回登录页：检查 APP_ORIGIN、浏览器地址与会话请求，详见 会话与访问控制。