推荐本地开发使用 pnpm，因为仓库包含 pnpm-lock.yaml：
pnpm installnpm 也可以使用，但不要在同一个 node_modules 中混用 npm 和 pnpm。如果要切换包管理器，请先删除 node_modules，再用目标包管理器重新安装。
本地 D1 测试替身依赖 better-sqlite3，它需要编译一个 native .node binding。pnpm 可能会在安装时先忽略依赖的构建脚本，直到你明确批准。
先查看当前被忽略的构建：
pnpm ignored-builds批准并重建本地开发会用到的包：
pnpm approve-builds better-sqlite3 esbuild workerd sharp
pnpm rebuild然后再运行：
pnpm run test这通常表示 JavaScript 依赖已经装好，但 better-sqlite3 的 native 二进制没有构建出来。这是本地安装环境问题，不是业务断言失败。按上一条批准 pnpm builds 并 rebuild 即可。
只要设置了 CF_ACCESS_TEAM_DOMAIN 或 CF_ACCESS_AUD，DEV_MODE 旁路就会被禁用。这是故意的安全护栏，避免生产 Access 配置意外启用本地免登录。
本地开发请保留：
DEV_MODE=true
DEV_USER_EMAIL=dev@localhost并保持以下变量未设置或注释：
# CF_ACCESS_TEAM_DOMAIN=...
# CF_ACCESS_AUD=...config.dbBindingMissing 表示当前运行时没有拿到 DB binding。请确认 wrangler.toml 存在，且 D1 binding 名称是 DB。
config.dbNotMigrated 表示 D1 表还不存在。运行：
pnpm run db:migrate远程 D1 则运行：
pnpm run db:migrate:remotepnpm run dev 启动 Astro dev server，带 HMR，是最快的本地开发流程。
pnpm run preview 会用 wrangler pages dev ./dist 跑生产构建产物。需要先运行 pnpm run build。当你要验证 workerd 行为、Cloudflare adapter 行为或生产 SSR 输出时，用 preview。
Cloudflare workerd 没有 MessageChannel，所以生产构建必须使用 react-dom/server.edge。但这个 edge 入口不适合 Astro 的 Vite dev module runner，因此 alias 只在 astro build 时启用。
最小读取权限：
- Zones / DNS：
Zone: Read、DNS: Edit - Workers & Pages：
Account Settings: Read、Workers Scripts: Read、Cloudflare Pages: Read - R2（桶/对象浏览、预览、预签名下载）：
Workers R2 Storage: Read - 用量页（含 R2 桶用量图表）：
Account Analytics: Read
写操作需要对应 Edit 权限：
- Pages 写操作：
Cloudflare Pages: Edit - Workers 写操作：
Workers Scripts: Edit - R2 写操作（上传、删除对象、建桶/删桶、设置修改）：
Workers R2 Storage: Edit
缺少 Edit 权限时，应只让对应写操作返回 403；只读页面不应因此不可用。
同步按账号独立执行并记录单账号失败。某个 Token 过期或权限不足，不应该影响其他账号刷新缓存。
不会。Token 存储前会使用 ENCRYPTION_KEY 做 AES-GCM 加密。系统另存 SHA-256 hash，用于同一用户下的 Token 去重。不要记录解密后的 Token，也不要通过 API 返回它。
用户数据隔离在 SQL 层通过 owner_email = ? 保证。新增任何触及用户数据的查询时，都要使用 appContext() 中的当前 userEmail 过滤。跨用户资源应该表现为资源不存在。