本地开发

准备修改 Calends 源码时，按本页启动开发环境并运行相关检查。

安装 Node.js 22，克隆仓库并执行下面的初始化命令。
打开本地后台；需要跳过登录时按下面说明修改 .dev.vars。
修改代码后运行与改动相关的检查；提交前检查下方完整清单。

启动

需要 Node.js 22。

git clone https://github.com/imetn/calends && cd calends
npm ci
npm run db:migrate:local
npm run dev

如需跳过本地登录，在 .dev.vars 中添加 DEV_BYPASS_AUTH=1，保留文件里已有的内容。

npm run dev 同时启动两个进程：Vite（前端，热更新，:5173）和 wrangler（Worker 与本地 D1，:8787）。打开 http://127.0.0.1:5173/admin。

本地数据库保存在仓库根目录的 .wrangler/state。

常用命令

命令	作用
`npm test`	单元测试（计费、阶段、指标、合租、分类等）
`npm run typecheck`	TypeScript 类型检查
`npm run lint`	oxlint
`npm run format` / `npm run format:check`	Prettier 格式化 / 检查
`npm run i18n:check`	检查每种语言是否都有全部文案
`npm run build`	生产构建
`npm run email:preview`	用示例数据把各种提醒邮件渲染成 HTML，写到 `.preview/email/`，不发送
`npm run demo`	生成虚构用户 Alex 的演示账本，写入本地数据库

代码结构

src/        后台与公开页
shared/     计费、阶段、指标、汇率、脱敏、多语言，浏览器和 Worker 共用
worker/     接口、登录（密码与 Passkey）、MCP、提醒与通知渠道、备份、ICS
migrations/ D1 / SQLite 数据库结构
docker/     自托管镜像的入口

技术栈：后台用 React 19（开启 React Compiler）和 Vite，弹窗、菜单、开关等交互组件基于 react-aria-components；公开页用 shadcn/ui；服务端是 Cloudflare Workers + D1。

提交前

npm run typecheck && npm run lint && npm run format:check && npm run i18n:check && npm test && npm run build

几条约定（详见仓库的 CONTRIBUTING.md）：

领域逻辑放在 shared/，必须同时能在浏览器和 Worker 里运行，不能用 DOM 或 Node API。改了计费、阶段或指标，在 shared/*.test.ts 里补单元测试。
所有用户能看到的文字都经过 t()，不要在模块顶层调用 t()。新文案至少要加到 en 和 zh-CN。
保持历史数据兼容。 旧记录必须一直可用；结构变化写成 migrations/ 下的新文件；新数据要能在备份里往返。
隐私：任何能识别人或账号的信息都不能出现在公开页，shared/mask.ts 用白名单决定公开什么。
保持界面和现有组件一致，检查手机宽度（390px）、桌面、亮色和暗色。