RuiToolAI on HanGR的碎碎念

Vinext：用 Vite 替代 Next.js 构建

Sat, 21 Mar 2026 00:00:00 +0000

为什么要迁移到 Vinext

RuiToolAI 最初是用标准 Next.js 开发的。但部署到 Cloudflare Workers 时遇到了一个根本问题：Next.js 需要 Node.js 运行时，Workers 基于 V8 引擎，它们不兼容。

当时只有一个选择：

OpenNext + SST：用 OpenNext 把 Next.js 编译成 Workers 兼容代码

但是，现在有了新的选择：Vinext

Vinext 是什么

2026年2月24日，Cloudflare 正式发布了 Vinext。这也是我们从 OpenNext 迁移过来的直接契机——官方工具出来了，没理由继续用绕弯子的方案。

Vinext 是 Cloudflare 的一个实验性项目，核心思路是：用 Vite 实现 Next.js 的公开 API 接口。

它保留了 Next.js 的 App Router、React Server Components、Server Actions、Route Handlers 等核心功能，但底层构建换成了 Vite。

1
2
3
4
5
6
7
8


# 开发 — 和 Next.js 一样的体验
pnpm dev

# 构建
pnpm build

# 部署
pnpm deploy

选择 Vinext，因为：

Cloudflare 官方维护，长期支持更有保障
Vite 构建速度更快
对 Workers 的原生支持更好

迁移过程

1. 安装 Vinext

1

pnpm add vinext

2. 替换 package.json 里的脚本

1
2
3
4
5
6
7
8


{
 "scripts": {
 "dev": "vinext dev",
 "build": "vinext build",
 "start": "vinext start",
 "deploy": "vinext deploy"
 }
}

3. 创建 worker-entrypoint.ts

Vinext 需要这个文件作为 Workers 的入口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


import { getCloudflareContext } from "./src/utils/cloudflare-context";
import { createHandler } from "vinext";

const handler = await createHandler({
 getCloudflareContext,
 // 配置 KV 缓存
 cache: {
 handler: new KVCacheHandler(env.NEXT_INC_CACHE_KV, {
 appPrefix: "ruitoolai",
 }),
 },
});

export default {
 fetch: handler.fetch,
 scheduled: async (event, env, ctx) => {
 ctx.waitUntil(cleanupExpiredImageRecords(env));
 },
};

4. 运行兼容性检查

1

pnpm run check:vinext

这个命令会扫描项目，找出不兼容的代码。比如：

使用了 Node.js 原生模块（fs, net, crypto 等）
使用了 Workers 不支持的 API

5. 修复兼容性问题

主要修复了三类问题：

a) 替换 crypto 模块

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 之前
import crypto from "crypto";
const hash = crypto.createHash("sha256").update(data).digest("hex");

// 之后
const encoder = new TextEncoder();
const data = encoder.encode(input);
const hashBuffer = await crypto.subtle.digest("SHA-256", data);
const hash = Array.from(new Uint8Array(hashBuffer))
 .map(b => b.toString(16).padStart(2, "0"))
 .join("");

b) 替换文件系统操作

Workers 没有 fs 模块，文件操作改为 R2：

1
2
3
4
5
6
7
8


// 之前：本地文件
import fs from "fs";
const buffer = fs.readFileSync("./template.html");

// 之后：R2 存储
const { env } = await getCloudflareContext();
const object = await env.USER_UPLOADS_BUCKET.get("template.html");
const buffer = await object.arrayBuffer();

c) 处理 Edge Runtime 差异

一些中间件和库需要适配 Edge Runtime：

1
2
3
4
5
6


// vite.config.ts
export default defineConfig({
 ssr: {
 noExternal: ["@some-edge-incompatible-lib"],
 },
});

遇到的坑和解决方案

坑 1：`waitUntil` 里的 setTimeout 不生效

Workers 的 setTimeout 不会真正 sleep，导致后台轮询任务瞬间跑完。

解决方案： 改用前端轮询 Server Action。

坑 2：某些 npm 包在构建时报错

部分包在 Vite 构建时报 dynamic require 相关的错误。

解决方案： 在 vite.config.ts 中配置 ssr.noExternal 或 optimizeDeps.exclude。

坑 3：热更新偶尔失效

Vinext 的 dev server 热更新偶尔不生效，需要手动刷新。

解决方案： 这是已知问题，社区正在修复。临时方案是 pnpm dev --force。

性能对比

指标	Next.js + OpenNext	Vinext
开发启动	8-15s	3-5s
构建时间	45-60s	20-30s
热更新	200-500ms	100-300ms
生产包大小	2.5MB	1.8MB
冷启动	500ms	300ms

总结

Vinext 目前还处于实验阶段，但对于 RuiToolAI 这种项目来说，它已经足够稳定。迁移带来的好处是：

构建速度提升 50%
包体积减少 30%
与 Cloudflare Workers 的原生集成

如果你也在用 Next.js + Cloudflare Workers，Vinext 值得一试。但建议先在测试环境跑通完整流程，确认兼容性后再上生产。

参考资源

GitHub Actions 全自动 CI/CD 流水线

Wed, 18 Jun 2025 00:00:00 +0000

每次 push 自动跑测试、自动部署到 Cloudflare Workers。这篇记录 RuiToolAI 的 CI/CD 搭建过程。

流水线设计

RuiToolAI 的 CI/CD 分两个阶段：

1
2
3
4
5
6
7


Push to main
 ↓
[CI] Lint + TypeCheck + Unit Tests
 ↓ 通过
[CD] Build + e2e Tests + Deploy to Cloudflare Workers
 ↓ 通过
生产环境更新

PR 只跑 CI，不部署。合并到 main 才触发部署。

基础 CI 配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


# .github/workflows/ci.yml
name: CI

on:
 push:
 branches: [main]
 pull_request:
 branches: [main]

jobs:
 lint-and-typecheck:
 name: Lint & TypeCheck
 runs-on: ubuntu-latest

 steps:
 - name: Checkout
 uses: actions/checkout@v4

 - name: Setup pnpm
 uses: pnpm/action-setup@v4
 with:
 version: 9

 - name: Setup Node.js
 uses: actions/setup-node@v4
 with:
 node-version: "20"
 cache: "pnpm"

 - name: Install dependencies
 run: pnpm install --frozen-lockfile

 - name: Lint
 run: pnpm run lint

 - name: TypeCheck
 run: pnpm run typecheck

 unit-tests:
 name: Unit Tests
 runs-on: ubuntu-latest
 needs: lint-and-typecheck

 steps:
 - uses: actions/checkout@v4
 - uses: pnpm/action-setup@v4
 with:
 version: 9
 - uses: actions/setup-node@v4
 with:
 node-version: "20"
 cache: "pnpm"
 - run: pnpm install --frozen-lockfile
 - run: pnpm run test

Cloudflare Workers 自动部署

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


# .github/workflows/deploy.yml
name: Deploy

on:
 push:
 branches: [main]

jobs:
 deploy:
 name: Deploy to Cloudflare Workers
 runs-on: ubuntu-latest
 # 只在 CI 通过后部署
 needs: [lint-and-typecheck, unit-tests]

 steps:
 - name: Checkout
 uses: actions/checkout@v4

 - name: Setup pnpm
 uses: pnpm/action-setup@v4
 with:
 version: 9

 - name: Setup Node.js
 uses: actions/setup-node@v4
 with:
 node-version: "20"
 cache: "pnpm"

 - name: Install dependencies
 run: pnpm install --frozen-lockfile

 - name: Build
 run: pnpm run build
 env:
 # 构建时需要的环境变量
 NODE_ENV: production

 - name: Deploy to Cloudflare Workers
 run: pnpm run deploy
 env:
 CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Secrets 管理

GitHub Actions 里的 Secrets 分两种：

Repository Secrets：只有这个仓库能用
Environment Secrets：绑定到特定环境（production/staging），可以设置审批流程

在 GitHub 仓库 → Settings → Secrets and variables → Actions 里配置。

RuiToolAI 需要的 Secrets：

1
2
3
4


CLOUDFLARE_API_TOKEN # Cloudflare API Token（Workers 部署权限）
CLOUDFLARE_ACCOUNT_ID # Cloudflare 账户 ID
TEST_USER_EMAIL # e2e 测试用的测试账号
TEST_USER_PASSWORD # e2e 测试用的测试密码

生成 Cloudflare API Token

登录 Cloudflare Dashboard
My Profile → API Tokens → Create Token
选择 “Edit Cloudflare Workers” 模板
复制 Token，粘贴到 GitHub Secrets

注意：Token 只显示一次，要立即保存。

e2e 测试集成

e2e 测试需要启动完整的应用，比较耗时，放在单独的 job 里：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


# .github/workflows/e2e.yml
name: E2E Tests

on:
 push:
 branches: [main]

jobs:
 e2e:
 name: End-to-End Tests
 runs-on: ubuntu-latest
 timeout-minutes: 30

 steps:
 - uses: actions/checkout@v4

 - uses: pnpm/action-setup@v4
 with:
 version: 9

 - uses: actions/setup-node@v4
 with:
 node-version: "20"
 cache: "pnpm"

 - run: pnpm install --frozen-lockfile

 # 安装 Playwright 浏览器
 - name: Install Playwright Browsers
 run: pnpm exec playwright install --with-deps chromium

 # 初始化本地测试数据库
 - name: Setup test database
 run: pnpm db:migrate:local

 # 运行 e2e 测试
 - name: Run e2e tests
 run: pnpm test:e2e
 env:
 TEST_USER_EMAIL: ${{ secrets.TEST_USER_EMAIL }}
 TEST_USER_PASSWORD: ${{ secrets.TEST_USER_PASSWORD }}

 # 失败时上传报告
 - name: Upload Playwright Report
 uses: actions/upload-artifact@v4
 if: failure()
 with:
 name: playwright-report
 path: playwright-report/
 retention-days: 7

数据库迁移自动化

部署前需要先跑数据库迁移，确保 schema 是最新的：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


- name: Run database migrations
 run: pnpm db:migrate:remote
 env:
 CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

- name: Deploy to Cloudflare Workers
 run: pnpm run deploy
 env:
 CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

package.json 里的迁移命令：

1
2
3
4
5
6


{
 "scripts": {
 "db:migrate:local": "wrangler d1 migrations apply DB --local",
 "db:migrate:remote": "wrangler d1 migrations apply DB --remote"
 }
}

部署通知

部署成功或失败时发通知，方便及时知道状态：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


- name: Notify on success
 if: success()
 run: |
 curl -X POST ${{ secrets.SLACK_WEBHOOK_URL }} \
 -H 'Content-type: application/json' \
 -d '{"text": "✅ RuiToolAI 部署成功！"}'

- name: Notify on failure
 if: failure()
 run: |
 curl -X POST ${{ secrets.SLACK_WEBHOOK_URL }} \
 -H 'Content-type: application/json' \
 -d '{"text": "❌ RuiToolAI 部署失败，请检查 GitHub Actions 日志。"}'

完整流水线示例

把所有 job 整合到一个文件里，用 needs 控制依赖关系：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88


# .github/workflows/main.yml
name: CI/CD

on:
 push:
 branches: [main]
 pull_request:
 branches: [main]

jobs:
 # 1. 代码质量检查（所有 push 和 PR 都跑）
 quality:
 name: Lint & TypeCheck
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - uses: pnpm/action-setup@v4
 with: { version: 9 }
 - uses: actions/setup-node@v4
 with: { node-version: "20", cache: "pnpm" }
 - run: pnpm install --frozen-lockfile
 - run: pnpm run lint
 - run: pnpm run typecheck

 # 2. 单元测试
 test:
 name: Unit Tests
 runs-on: ubuntu-latest
 needs: quality
 steps:
 - uses: actions/checkout@v4
 - uses: pnpm/action-setup@v4
 with: { version: 9 }
 - uses: actions/setup-node@v4
 with: { node-version: "20", cache: "pnpm" }
 - run: pnpm install --frozen-lockfile
 - run: pnpm run test

 # 3. e2e 测试（只在 main 分支跑）
 e2e:
 name: E2E Tests
 runs-on: ubuntu-latest
 needs: test
 if: github.ref == 'refs/heads/main'
 steps:
 - uses: actions/checkout@v4
 - uses: pnpm/action-setup@v4
 with: { version: 9 }
 - uses: actions/setup-node@v4
 with: { node-version: "20", cache: "pnpm" }
 - run: pnpm install --frozen-lockfile
 - run: pnpm exec playwright install --with-deps chromium
 - run: pnpm db:migrate:local
 - run: pnpm test:e2e
 env:
 TEST_USER_EMAIL: ${{ secrets.TEST_USER_EMAIL }}
 TEST_USER_PASSWORD: ${{ secrets.TEST_USER_PASSWORD }}
 - uses: actions/upload-artifact@v4
 if: failure()
 with:
 name: playwright-report
 path: playwright-report/
 retention-days: 7

 # 4. 部署（只在 main 分支，所有测试通过后）
 deploy:
 name: Deploy
 runs-on: ubuntu-latest
 needs: [test, e2e]
 if: github.ref == 'refs/heads/main'
 steps:
 - uses: actions/checkout@v4
 - uses: pnpm/action-setup@v4
 with: { version: 9 }
 - uses: actions/setup-node@v4
 with: { node-version: "20", cache: "pnpm" }
 - run: pnpm install --frozen-lockfile
 - run: pnpm run build
 - name: Run DB migrations
 run: pnpm db:migrate:remote
 env:
 CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
 - name: Deploy to Workers
 run: pnpm run deploy
 env:
 CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

常见问题排查

问题 1：pnpm install 很慢

加缓存：

1
2
3
4


- uses: actions/setup-node@v4
 with:
 node-version: "20"
 cache: "pnpm" # 这行很重要

问题 2：Playwright 浏览器每次都重新下载

1
2
3
4
5
6
7
8


- name: Cache Playwright browsers
 uses: actions/cache@v4
 with:
 path: ~/.cache/ms-playwright
 key: playwright-${{ runner.os }}-${{ hashFiles('**/package.json') }}

- name: Install Playwright Browsers
 run: pnpm exec playwright install --with-deps chromium

问题 3：部署失败但没有详细错误信息

1
2
3
4
5
6


- name: Deploy
 run: pnpm run deploy
 env:
 CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 # 加上 --verbose 看详细日志
 # 或者检查 wrangler 版本是否兼容

问题 4：e2e 测试超时

1
2
3


jobs:
 e2e:
 timeout-minutes: 30 # 增加超时时间

总结

CI/CD 流水线的核心原则：

快速反馈：Lint 和 TypeCheck 最快，先跑；e2e 最慢，最后跑
依赖关系：用 needs 控制 job 顺序，测试通过才部署
分支策略：PR 只跑 CI，main 分支才部署
Secrets 安全：敏感信息放 GitHub Secrets，不要硬编码
失败保留证据：上传测试报告，方便排查

参考资源

Vitest + Playwright 全栈 e2e 测试实战

Wed, 23 Apr 2025 00:00:00 +0000

测试不是可选项。这篇记录 RuiToolAI 的测试体系搭建，以及踩过的 SQLite 并发锁这个大坑。

测试策略

RuiToolAI 的测试分两层：

层级	工具	覆盖范围
单元/集成测试	Vitest	工具函数、Server Actions、数据库操作
e2e 测试	Playwright	完整用户流程（注册、登录、生成图片）

原则：e2e 测试覆盖核心用户旅程，单元测试覆盖复杂业务逻辑。 不追求 100% 覆盖率，追求关键路径不出错。

Vitest 单元测试配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// vitest.config.ts
import { defineConfig } from "vitest/config";
import path from "path";

export default defineConfig({
 test: {
 environment: "node",
 globals: true,
 setupFiles: ["./src/test/setup.ts"],
 },
 resolve: {
 alias: {
 "@": path.resolve(__dirname, "./src"),
 },
 },
});

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// src/test/setup.ts
import { beforeAll, afterAll } from "vitest";

// 全局测试前置
beforeAll(async () => {
 // 初始化测试数据库
});

afterAll(async () => {
 // 清理
});

Playwright e2e 测试配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
 testDir: "./e2e",
 fullyParallel: true,
 forbidOnly: !!process.env.CI,
 retries: process.env.CI ? 2 : 0,
 workers: process.env.CI ? 1 : undefined,
 reporter: "html",

 use: {
 baseURL: "http://localhost:3000",
 trace: "on-first-retry",
 },

 projects: [
 {
 name: "chromium",
 use: { ...devices["Desktop Chrome"] },
 },
 ],

 // 测试前启动开发服务器
 webServer: {
 command: "pnpm dev",
 url: "http://localhost:3000",
 reuseExistingServer: !process.env.CI,
 timeout: 120 * 1000,
 },
});

测试数据库隔离

e2e 测试不能用生产数据库，需要独立的测试数据库。

在 Cloudflare Workers 本地开发环境里，Wrangler 会自动创建本地 SQLite 文件：

1
2
3


.wrangler/state/v3/d1/
└── <database-id>/
 └── db.sqlite ← 本地测试用这个

测试前需要初始化 schema：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// e2e/fixtures/db.ts
import { execSync } from "child_process";

export function setupTestDb() {
 // 应用所有迁移
 execSync("pnpm db:migrate:local", { stdio: "inherit" });
}

export function cleanTestDb() {
 // 清理测试数据
 execSync(
 'wrangler d1 execute DB --local --command "DELETE FROM users WHERE email LIKE \'%test%\'"',
 { stdio: "inherit" }
 );
}

SQLite 并发锁问题及解决

这是我踩过最深的坑。

问题现象

CI 里 e2e 测试随机失败，错误信息：

1

SqliteError: database is locked

原因分析

Vitest 默认并行运行多个测试文件，每个文件在独立的 Worker 线程里执行。多个线程同时写同一个 SQLite 文件，就会出现锁冲突。

SQLite 的写锁是文件级别的，同一时刻只允许一个写操作。

解决方案

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// vitest.e2e.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
 test: {
 // 关键：禁用文件级并行，改为串行执行
 fileParallelism: false,
 // 只用一个 Worker
 maxWorkers: 1,
 // 测试文件内部的测试用例仍然可以并行
 // （但写数据库的测试用例最好也串行）
 },
});

代价是测试速度变慢，但在 CI 里稳定性更重要。

为什么之前没问题？

本地开发时，测试文件少，并发冲突概率低。CI 里测试文件多，并发冲突必然发生。

常用测试模式

测试 Server Action

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


// src/app/(auth)/sign-up/sign-up.actions.test.ts
import { describe, it, expect, beforeEach } from "vitest";
import { signUpAction } from "./sign-up.actions";

describe("signUpAction", () => {
 it("应该成功注册新用户", async () => {
 const result = await signUpAction({
 email: "test@example.com",
 password: "Password123!",
 });

 expect(result?.data?.success).toBe(true);
 });

 it("应该拒绝已存在的邮箱", async () => {
 // 先注册一次
 await signUpAction({
 email: "existing@example.com",
 password: "Password123!",
 });

 // 再注册同一个邮箱
 const result = await signUpAction({
 email: "existing@example.com",
 password: "Password123!",
 });

 expect(result?.serverError).toBeDefined();
 });
});

Playwright 测试登录流程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


// e2e/auth.spec.ts
import { test, expect } from "@playwright/test";

test.describe("认证流程", () => {
 test("用户可以注册并登录", async ({ page }) => {
 // 访问注册页
 await page.goto("/sign-up");

 // 填写表单
 await page.fill('[name="email"]', "e2e-test@example.com");
 await page.fill('[name="password"]', "TestPassword123!");

 // 提交
 await page.click('[type="submit"]');

 // 验证跳转到 dashboard
 await expect(page).toHaveURL("/dashboard");
 await expect(page.locator("h1")).toContainText("欢迎");
 });

 test("错误密码应该显示错误提示", async ({ page }) => {
 await page.goto("/sign-in");
 await page.fill('[name="email"]', "user@example.com");
 await page.fill('[name="password"]', "wrongpassword");
 await page.click('[type="submit"]');

 await expect(page.locator('[role="alert"]')).toBeVisible();
 });
});

测试需要认证的页面

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


// e2e/fixtures/auth.ts
import { test as base, expect } from "@playwright/test";

// 扩展 test，自动登录
export const test = base.extend({
 page: async ({ page }, use) => {
 // 登录
 await page.goto("/sign-in");
 await page.fill('[name="email"]', process.env.TEST_USER_EMAIL!);
 await page.fill('[name="password"]', process.env.TEST_USER_PASSWORD!);
 await page.click('[type="submit"]');
 await page.waitForURL("/dashboard");

 await use(page);
 },
});

export { expect };

1
2
3
4
5
6
7


// e2e/history.spec.ts
import { test, expect } from "./fixtures/auth";

test("历史页面应该显示生成记录", async ({ page }) => {
 await page.goto("/history");
 await expect(page.locator("h1")).toContainText("生成历史");
});

使用 Page Object Model

对于复杂页面，用 Page Object Model 封装操作：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


// e2e/pages/image-gen.page.ts
import { Page } from "@playwright/test";

export class ImageGenPage {
 constructor(private page: Page) {}

 async goto() {
 await this.page.goto("/image-gen");
 }

 async generateImage(prompt: string) {
 await this.page.fill("textarea", prompt);
 await this.page.click('[data-testid="generate-button"]');
 }

 async waitForGeneration() {
 // 等待生成完成（最多 60 秒）
 await this.page.waitForSelector('[data-testid="generated-image"]', {
 timeout: 60000,
 });
 }

 async getGeneratedImageUrl() {
 return this.page
 .locator('[data-testid="generated-image"]')
 .getAttribute("src");
 }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// e2e/image-gen.spec.ts
import { test, expect } from "./fixtures/auth";
import { ImageGenPage } from "./pages/image-gen.page";

test("用户可以生成图片", async ({ page }) => {
 const imageGenPage = new ImageGenPage(page);
 await imageGenPage.goto();
 await imageGenPage.generateImage("a beautiful sunset over the ocean");
 await imageGenPage.waitForGeneration();

 const imageUrl = await imageGenPage.getGeneratedImageUrl();
 expect(imageUrl).toBeTruthy();
});

CI 里运行测试

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# .github/workflows/ci.yml
- name: Run e2e tests
 run: pnpm test:e2e
 env:
 TEST_USER_EMAIL: ${{ secrets.TEST_USER_EMAIL }}
 TEST_USER_PASSWORD: ${{ secrets.TEST_USER_PASSWORD }}

- name: Upload test results
 uses: actions/upload-artifact@v4
 if: failure()
 with:
 name: playwright-report
 path: playwright-report/
 retention-days: 7

测试失败时上传报告，方便排查问题。

总结

全栈测试体系的关键点：

分层测试：单元测试覆盖逻辑，e2e 测试覆盖用户旅程
数据库隔离：测试用独立的本地 SQLite，不污染生产数据
串行执行：SQLite 不支持并发写，fileParallelism: false 是必须的
Page Object Model：复杂页面封装操作，测试代码更易维护
CI 上传报告：失败时保留截图和 trace，方便排查

参考资源

自建类型安全的多语言 i18n 方案

Thu, 20 Feb 2025 00:00:00 +0000

为什么不用 next-intl

next-intl 是最流行的 Next.js 国际化方案，但有几个问题：

需要在路由层面做语言切换（/en/xxx、/zh/xxx），改动较大
对于 RuiToolAI 这种主要面向英文用户的产品，路由级别的 i18n 过于复杂

所以选择了自建一个轻量的 i18n 方案，核心特点是编译期类型检查。

方案设计

1
2
3
4
5
6
7


src/i18n/
 keys.ts # 所有翻译 key 的联合类型
 messages.ts # createT 函数
 locale.ts # 获取当前语言
 locales/
 en.ts # 英文翻译
 zh.ts # 中文翻译（可选）

Key 的类型定义

所有翻译 key 定义为 TypeScript 联合类型：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


// src/i18n/keys.ts
export type I18nKey =
 // Navigation
 | "nav.home"
 | "nav.pricing"
 | "nav.docs"

 // Auth
 | "auth.signIn"
 | "auth.signUp"
 | "auth.signOut"
 | "auth.email"
 | "auth.password"

 // Landing
 | "landing.hero.title"
 | "landing.hero.description"
 | "landing.features.title"
 | "landing.testimonials.title"
 | "landing.testimonials.subtitle"
 | "landing.testimonials.description"

 // Sidebar
 | "sidebar.dashboard"
 | "sidebar.billing"
 | "sidebar.settings"
 | "sidebar.history"
 | "sidebar.adminPanel"

 // Footer
 | "footer.copyright"
 | "footer.socialXSrOnly"
 | "footer.socialInstagramSrOnly"
 | "footer.socialEmailSrOnly"

 // Errors
 | "error.notFound"
 | "error.serverError";

关键点： 这是一个 TypeScript 联合类型，不是枚举。这意味着：

使用不存在的 key 会在编译期报错
IDE 有自动补全
重命名 key 时，TypeScript 会提示所有使用处

翻译文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


// src/i18n/locales/en.ts
import type { I18nKey } from "../keys";

// Record<I18nKey, string> 确保所有 key 都有翻译
export const en: Record<I18nKey, string> = {
 "nav.home": "Home",
 "nav.pricing": "Pricing",
 "nav.docs": "Docs",

 "auth.signIn": "Sign In",
 "auth.signUp": "Sign Up",
 "auth.signOut": "Sign Out",
 "auth.email": "Email",
 "auth.password": "Password",

 "landing.hero.title": "AI-Powered Creative Platform",
 "landing.hero.description": "Generate professional images in seconds",
 "landing.features.title": "Everything you need to create",
 "landing.testimonials.title": "Loved by Creators Worldwide",
 "landing.testimonials.subtitle": "Testimonials",
 "landing.testimonials.description": "Hear what our users have to say",

 "sidebar.dashboard": "Dashboard",
 "sidebar.billing": "Billing",
 "sidebar.settings": "Settings",
 "sidebar.history": "History",
 "sidebar.adminPanel": "Admin Panel",

 "footer.copyright": "© 2026 RuiToolAI. All rights reserved.",
 "footer.socialXSrOnly": "X (Twitter)",
 "footer.socialInstagramSrOnly": "Instagram",
 "footer.socialEmailSrOnly": "Email",

 "error.notFound": "Page not found",
 "error.serverError": "Something went wrong",
};

如果漏掉某个 key，TypeScript 会报错：

1
2


Type '{ "nav.home": string; ... }' is missing the following properties
from type 'Record<I18nKey, string>': "error.serverError"

服务端使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// src/i18n/messages.ts
import type { I18nKey } from "./keys";
import { en } from "./locales/en";

const locales = { en };

export function createT(locale: string) {
 const messages = locales[locale as keyof typeof locales] ?? en;
 return function t(key: I18nKey): string {
 return messages[key] ?? key;
 };
}

在 Server Component 中使用：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// src/components/landing/testimonials.tsx
import { getRequestLocale } from "@/i18n/locale";
import { createT } from "@/i18n/messages";

export async function Testimonials() {
 const locale = await getRequestLocale();
 const t = createT(locale);

 return (
 <div>
 <h2>{t("landing.testimonials.subtitle")}</h2>
 <h1>{t("landing.testimonials.title")}</h1>
 <p>{t("landing.testimonials.description")}</p>
 </div>
 );
}

客户端使用

客户端组件不能直接调用 getRequestLocale（Server 函数），需要通过 props 传入：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


// Server Component
export async function Sidebar() {
 const locale = await getRequestLocale();
 const t = createT(locale);

 return (
 <SidebarClient
 labels={{
 dashboard: t("sidebar.dashboard"),
 billing: t("sidebar.billing"),
 history: t("sidebar.history"),
 }}
 />
 );
}

// Client Component
export function SidebarClient({ labels }) {
 return (
 <nav>
 <a href="/dashboard">{labels.dashboard}</a>
 <a href="/dashboard/billing">{labels.billing}</a>
 <a href="/history">{labels.history}</a>
 </nav>
 );
}

添加新翻译的流程

在 src/i18n/keys.ts 添加新 key：

1
2
3
4


export type I18nKey =
 // ...
 | "landing.newSection.title" // 新增
 | "landing.newSection.description"; // 新增

在 src/i18n/locales/en.ts 添加翻译（TypeScript 会报错提醒你）：

1
2
3
4
5


export const en: Record<I18nKey, string> = {
 // ...
 "landing.newSection.title": "New Section",
 "landing.newSection.description": "Description here",
};

在组件中使用：

1
2


const t = createT(locale);
<h2>{t("landing.newSection.title")}</h2>

总结

这个自建 i18n 方案的核心优势：

特性	说明
编译期检查	用了不存在的 key 直接报错
自动补全	IDE 提示所有可用 key
零运行时错误	不会出现 key 找不到的情况
轻量	不依赖任何第三方库
简单	整个方案不到 100 行代码

对于不需要路由级别语言切换的项目，这个方案比 next-intl 更简单，而且类型安全性更好。

CSS 无限滚动 Marquee 动画实现

Wed, 22 Jan 2025 00:00:00 +0000

不用任何 JS 库，纯 CSS 实现无缝循环滚动。这是 RuiToolAI 客户评价组件的实现记录。

效果目标

卡片从右向左无限滚动
滚动无缝衔接，看不出循环点
鼠标悬停时暂停
两侧有渐变遮罩，边缘自然淡出
支持暗色模式

核心原理

Marquee 动画的本质是：用 CSS translateX 把一排元素从 0 移动到 -50%，然后瞬间重置到 0，循环播放。

为什么是 -50%？因为我把内容复制了一份，总宽度是原来的 2 倍。移动 -50% 正好是一份内容的宽度，重置后用户看不出来。

1
2
3
4
5


原始内容：[A][B][C][D]
复制后： [A][B][C][D][A][B][C][D]
 ←←←←←←←←←←←←←←←←←←←←
动画：从 translateX(0) 到 translateX(-50%)
重置：瞬间回到 translateX(0)，用户看到的还是 [A][B][C][D]

基础实现

先用纯 CSS 实现：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


/* 定义 marquee 动画 */
@keyframes marquee {
 from {
 transform: translateX(0);
 }
 to {
 transform: translateX(-50%);
 }
}

.marquee-track {
 display: flex;
 animation: marquee 30s linear infinite;
}

/* 容器需要 overflow-hidden */
.marquee-container {
 overflow: hidden;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


<div class="marquee-container">
 <div class="marquee-track">
 <!-- 原始内容 -->
 <div class="item">卡片 1</div>
 <div class="item">卡片 2</div>
 <div class="item">卡片 3</div>
 <!-- 复制一份，实现无缝循环 -->
 <div class="item">卡片 1</div>
 <div class="item">卡片 2</div>
 <div class="item">卡片 3</div>
 </div>
</div>

无缝循环的关键：复制元素

在 React 里，用 JS 复制数组：

1
2
3


const items = ["卡片1", "卡片2", "卡片3"];
// 复制一份，总共 6 个元素
const doubled = [...items, ...items];

1
2
3
4
5
6
7


<div className="flex animate-marquee">
 {doubled.map((item, i) => (
 <div key={i} className="flex-shrink-0 w-80">
 {item}
 </div>
 ))}
</div>

flex-shrink-0 很重要，防止卡片被压缩。

加入 Tailwind

在 tailwind.config.ts 里注册自定义动画：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// tailwind.config.ts
import type { Config } from "tailwindcss";

const config: Config = {
 theme: {
 extend: {
 keyframes: {
 marquee: {
 from: { transform: "translateX(0)" },
 to: { transform: "translateX(-50%)" },
 },
 },
 animation: {
 // 30s 速度，linear 匀速，infinite 无限循环
 marquee: "marquee 30s linear infinite",
 },
 },
 },
};

然后直接用 animate-marquee 类名：

1
2
3


<div className="flex animate-marquee">
 {/* 卡片 */}
</div>

hover 暂停

Tailwind 支持 [animation-play-state:paused] 这种任意值写法：

1
2
3


<div className="flex animate-marquee hover:[animation-play-state:paused]">
 {/* 鼠标悬停时暂停 */}
</div>

但有个问题：鼠标悬停在卡片上时，事件冒泡到父元素，动画暂停。但如果鼠标悬停在卡片之间的间隙，动画不会暂停。

更好的做法是把 hover 监听放在外层容器：

1
2
3
4
5


<div className="group overflow-hidden">
 <div className="flex animate-marquee group-hover:[animation-play-state:paused]">
 {/* 卡片 */}
 </div>
</div>

group + group-hover: 让父元素的 hover 状态控制子元素的动画。

两侧渐变遮罩

渐变遮罩让边缘自然淡出，视觉上更好看：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


<div className="relative overflow-hidden max-w-7xl mx-auto">
 {/* 左侧遮罩 */}
 <div
 className="absolute left-0 top-0 bottom-0 w-24 z-10 pointer-events-none
 bg-gradient-to-r from-background to-transparent"
 />

 {/* 右侧遮罩 */}
 <div
 className="absolute right-0 top-0 bottom-0 w-24 z-10 pointer-events-none
 bg-gradient-to-l from-background to-transparent"
 />

 {/* 滚动内容 */}
 <div className="flex gap-6 animate-marquee">
 {/* 卡片 */}
 </div>
</div>

关键细节：

pointer-events-none：遮罩不拦截鼠标事件，hover 暂停仍然有效
from-background：用语义化颜色，暗色模式自动适配
z-10：遮罩在卡片上层

响应式和暗色模式

卡片宽度在移动端可以小一点：

1
2
3


<div className="flex-shrink-0 w-72 sm:w-80 p-4 sm:p-6 rounded-xl border border-border bg-card">
 <p className="text-sm sm:text-base text-muted-foreground">{content}</p>
</div>

暗色模式用语义化颜色，不需要额外的 dark: 前缀：

1
2


// bg-card、text-card-foreground、border-border 都会随主题自动切换
<div className="bg-card text-card-foreground border border-border">

完整组件代码

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84


// src/components/landing/testimonials.tsx
"use client";

const testimonials = [
 {
 content: "RuiToolAI 的图片生成速度非常快，质量也很高。",
 name: "Sarah Chen",
 role: "UI 设计师",
 avatar: "https://images.unsplash.com/photo-1494790108377-be9c29b29330?w=100",
 },
 {
 content: "积分制度很合理，按需购买，不浪费。",
 name: "Marcus Johnson",
 role: "内容创作者",
 avatar: "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=100",
 },
 // ... 更多评价
];

// 复制一份实现无缝循环
const doubled = [...testimonials, ...testimonials];

export function Testimonials() {
 return (
 <section className="py-16 bg-background overflow-hidden">
 <div className="max-w-7xl mx-auto px-4 mb-12">
 <h2 className="text-3xl font-bold text-center text-foreground">
 用户怎么说
 </h2>
 <p className="text-center text-muted-foreground mt-4">
 来自真实用户的反馈
 </p>
 </div>

 {/* 滚动区域，限制最大宽度 */}
 <div className="relative max-w-7xl mx-auto overflow-hidden group">
 {/* 左侧渐变遮罩 */}
 <div className="absolute left-0 top-0 bottom-0 w-24 z-10 pointer-events-none bg-gradient-to-r from-background to-transparent" />

 {/* 右侧渐变遮罩 */}
 <div className="absolute right-0 top-0 bottom-0 w-24 z-10 pointer-events-none bg-gradient-to-l from-background to-transparent" />

 {/* 滚动轨道 */}
 <div className="flex gap-6 animate-marquee group-hover:[animation-play-state:paused]">
 {doubled.map((item, i) => (
 <div
 key={i}
 className="flex-shrink-0 w-80 p-6 rounded-xl border border-border bg-card shadow-sm"
 >
 {/* 星级评分 */}
 <div className="flex gap-1 mb-3">
 {Array.from({ length: 5 }).map((_, j) => (
 <span key={j} className="text-yellow-400 text-sm">
 ★
 </span>
 ))}
 </div>

 {/* 评价内容 */}
 <p className="text-muted-foreground text-sm leading-relaxed mb-4">
 "{item.content}"
 </p>

 {/* 用户信息 */}
 <div className="flex items-center gap-3">
 <img
 src={item.avatar}
 alt={item.name}
 className="w-10 h-10 rounded-full object-cover"
 />
 <div>
 <p className="font-medium text-foreground text-sm">
 {item.name}
 </p>
 <p className="text-xs text-muted-foreground">{item.role}</p>
 </div>
 </div>
 </div>
 ))}
 </div>
 </div>
 </section>
 );
}

常见问题

Q：滚动速度怎么调？

修改 tailwind.config.ts 里的动画时长：

1
2
3


animation: {
 marquee: "marquee 20s linear infinite", // 20s 更快，60s 更慢
},

Q：卡片数量少时循环点很明显怎么办？

复制更多份：

1
2
3


// 复制 3 份而不是 2 份
const tripled = [...items, ...items, ...items];
// 动画移动到 -33.33% 而不是 -50%

或者增加卡片数量，让一屏显示不完。

Q：移动端性能差怎么办？

用 will-change: transform 开启 GPU 加速：

1
2
3


.marquee-track {
 will-change: transform;
}

Tailwind 里：

1

<div className="flex animate-marquee will-change-transform">

Q：能反向滚动吗（从左向右）？

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// tailwind.config.ts
keyframes: {
 "marquee-reverse": {
 from: { transform: "translateX(-50%)" },
 to: { transform: "translateX(0)" },
 },
},
animation: {
 "marquee-reverse": "marquee-reverse 30s linear infinite",
},

总结

纯 CSS Marquee 的核心就三步：

复制内容：把数组 [...items, ...items]，总宽度翻倍
定义动画：translateX(0) → translateX(-50%)，linear，infinite
overflow-hidden：容器裁剪，只显示一半内容

加上渐变遮罩和 hover 暂停，效果就很完整了。

参考资源

Tailwind CSS 暗色模式从零搭建

Sat, 23 Nov 2024 00:00:00 +0000

暗色模式不只是加个 dark: 前缀那么简单。这篇记录我在 RuiToolAI 里搭建完整暗色模式体系的过程。

为什么暗色模式容易搞乱

暗色模式最常见的问题：

颜色硬编码：text-gray-900 在暗色下看不见
闪烁（FOUC）：页面加载时先显示亮色再切换到暗色
图片/图标不适配：亮色图标在暗色背景上消失
第三方组件不跟随：自己的组件暗色了，Shadcn 组件还是亮色

Tailwind 暗色模式配置

Tailwind 支持两种暗色模式策略：

1
2
3
4
5
6
7
8


// tailwind.config.ts
export default {
 // 方案一：跟随系统（media）
 darkMode: "media",

 // 方案二：手动切换（class）—— 推荐
 darkMode: "class",
};

推荐用 class 方案，因为：

用户可以手动切换，不受系统设置影响
可以持久化到 localStorage
SSR 时可以从 cookie 读取，避免闪烁

CSS 变量 + Tailwind 的组合方案

硬编码颜色是暗色模式的大敌。正确做法是用 CSS 变量定义语义化颜色：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


/* src/app/globals.css */
@layer base {
 :root {
 --background: 0 0% 100%;
 --foreground: 222.2 84% 4.9%;
 --card: 0 0% 100%;
 --card-foreground: 222.2 84% 4.9%;
 --primary: 221.2 83.2% 53.3%;
 --primary-foreground: 210 40% 98%;
 --muted: 210 40% 96.1%;
 --muted-foreground: 215.4 16.3% 46.9%;
 --border: 214.3 31.8% 91.4%;
 --radius: 0.5rem;
 }

 .dark {
 --background: 222.2 84% 4.9%;
 --foreground: 210 40% 98%;
 --card: 222.2 84% 4.9%;
 --card-foreground: 210 40% 98%;
 --primary: 217.2 91.2% 59.8%;
 --primary-foreground: 222.2 47.4% 11.2%;
 --muted: 217.2 32.6% 17.5%;
 --muted-foreground: 215 20.2% 65.1%;
 --border: 217.2 32.6% 17.5%;
 }
}

然后在 tailwind.config.ts 里把这些变量映射成 Tailwind 颜色：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


// tailwind.config.ts
import type { Config } from "tailwindcss";

const config: Config = {
 darkMode: "class",
 theme: {
 extend: {
 colors: {
 background: "hsl(var(--background))",
 foreground: "hsl(var(--foreground))",
 card: {
 DEFAULT: "hsl(var(--card))",
 foreground: "hsl(var(--card-foreground))",
 },
 primary: {
 DEFAULT: "hsl(var(--primary))",
 foreground: "hsl(var(--primary-foreground))",
 },
 muted: {
 DEFAULT: "hsl(var(--muted))",
 foreground: "hsl(var(--muted-foreground))",
 },
 border: "hsl(var(--border))",
 },
 },
 },
};

这样写组件时只需要用语义化类名，暗色模式自动切换：

1
2
3
4


// 不需要写 dark: 前缀
<div className="bg-background text-foreground">
 <p className="text-muted-foreground">副标题</p>
</div>

主题切换实现

避免闪烁的关键

闪烁（FOUC）发生在：服务端渲染了亮色 HTML，客户端 JS 加载后才切换到暗色，用户看到一闪。

解决方案：在 <head> 里内联一段脚本，在页面渲染前就设置好 class：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


// src/app/layout.tsx
export default function RootLayout({
 children,
}: {
 children: React.ReactNode;
}) {
 return (
 <html lang="zh" suppressHydrationWarning>
 <head>
 {/* 内联脚本，在 HTML 解析时立即执行，避免闪烁 */}
 <script
 dangerouslySetInnerHTML={{
 __html: `
 (function() {
 try {
 var theme = localStorage.getItem('theme');
 if (theme === 'dark' || (!theme && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
 document.documentElement.classList.add('dark');
 }
 } catch (e) {}
 })();
 `,
 }}
 />
 </head>
 <body>{children}</body>
 </html>
 );
}

suppressHydrationWarning 是必须的，因为服务端和客户端的 class 可能不同。

主题切换组件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


// src/components/theme-toggle.tsx
"use client";
import { useEffect, useState } from "react";
import { SunIcon, MoonIcon } from "@heroicons/react/24/outline";

export function ThemeToggle() {
 const [isDark, setIsDark] = useState(false);

 useEffect(() => {
 // 初始化时读取当前主题
 setIsDark(document.documentElement.classList.contains("dark"));
 }, []);

 function toggle() {
 const next = !isDark;
 setIsDark(next);
 if (next) {
 document.documentElement.classList.add("dark");
 localStorage.setItem("theme", "dark");
 } else {
 document.documentElement.classList.remove("dark");
 localStorage.setItem("theme", "light");
 }
 }

 return (
 <button
 onClick={toggle}
 className="rounded-md p-2 hover:bg-muted transition-colors"
 aria-label={isDark ? "切换到亮色模式" : "切换到暗色模式"}
 >
 {isDark ? (
 <SunIcon className="h-5 w-5" />
 ) : (
 <MoonIcon className="h-5 w-5" />
 )}
 </button>
 );
}

Shadcn UI 的暗色模式集成

Shadcn UI 的组件本身已经支持暗色模式，因为它们内部用的就是 CSS 变量（bg-background、text-foreground 等）。

只要你的 CSS 变量配置正确，Shadcn 组件会自动跟随主题切换。

但有一个坑：Shadcn 的 cn() 工具函数。

1
2
3
4
5
6
7


// src/lib/utils.ts
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
 return twMerge(clsx(inputs));
}

当你用 dark: 前缀覆盖 Shadcn 组件的默认样式时，twMerge 会正确处理冲突，不会出现样式叠加问题。

常见坑点

坑 1：图片在暗色下太亮

1
2
3
4
5
6


// 给图片加暗色滤镜
<img
 src="/logo.png"
 className="dark:brightness-90 dark:invert"
 alt="Logo"
/>

坑 2：渐变在暗色下不好看

1
2


// 亮色：浅蓝渐变；暗色：深蓝渐变
<div className="bg-gradient-to-r from-blue-50 to-indigo-50 dark:from-blue-950 dark:to-indigo-950">

坑 3：边框在暗色下消失

1
2
3
4


// 用语义化 border 颜色
<div className="border border-border">
 {/* border 颜色会随主题切换 */}
</div>

坑 4：第三方库的弹窗/Portal 不跟随主题

有些第三方库把弹窗挂载到 document.body，不在 .dark 类的作用范围内。

解决方案：把 .dark 类加到 <html> 而不是 <body>，这样所有子元素都能继承。

实战：给 Testimonials 组件加暗色支持

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


// src/components/landing/testimonials.tsx
export function Testimonials() {
 return (
 <section className="py-16 bg-background">
 <div className="max-w-7xl mx-auto px-4">
 <h2 className="text-3xl font-bold text-center text-foreground mb-12">
 用户评价
 </h2>

 {/* 滚动容器 */}
 <div className="relative overflow-hidden">
 {/* 左侧渐变遮罩 */}
 <div className="absolute left-0 top-0 bottom-0 w-24 z-10 bg-gradient-to-r from-background to-transparent" />

 {/* 右侧渐变遮罩 */}
 <div className="absolute right-0 top-0 bottom-0 w-24 z-10 bg-gradient-to-l from-background to-transparent" />

 <div className="flex gap-6 animate-marquee hover:[animation-play-state:paused]">
 {testimonials.map((item, i) => (
 <div
 key={i}
 className="flex-shrink-0 w-80 p-6 rounded-xl border border-border bg-card text-card-foreground shadow-sm"
 >
 <p className="text-muted-foreground mb-4">{item.content}</p>
 <div className="flex items-center gap-3">
 <img
 src={item.avatar}
 alt={item.name}
 className="w-10 h-10 rounded-full object-cover"
 />
 <div>
 <p className="font-medium text-foreground">{item.name}</p>
 <p className="text-sm text-muted-foreground">{item.role}</p>
 </div>
 </div>
 </div>
 ))}
 </div>
 </div>
 </div>
 </section>
 );
}

注意渐变遮罩用的是 from-background，这样在暗色模式下遮罩颜色也会自动切换，不会出现白色遮罩盖在暗色背景上的问题。

总结

搭建完整暗色模式体系的关键步骤：

CSS 变量定义语义化颜色：:root 和 .dark 分别定义
Tailwind 映射 CSS 变量：tailwind.config.ts 里配置
内联脚本避免闪烁：在 <head> 里提前设置 class
组件用语义化类名：bg-background、text-foreground，而不是 bg-white、text-gray-900
渐变遮罩用语义化颜色：from-background 而不是 from-white

参考资源

自建 CMS 系统：从数据库到富文本编辑器

Mon, 14 Oct 2024 00:00:00 +0000

为什么自建 CMS

RuiToolAI 需要管理：

网站导航（顶部菜单、Footer 链接）
博客文章、文档页面
媒体资源（图片、文件）
FAQ 内容

用第三方 CMS（Contentful、Sanity）需要额外付费，而且数据不在自己手里。自建 CMS 虽然工作量大，但完全可控，而且可以复用到其他站点。

数据库表设计

导航节点表

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


export const cmsNavigationNodeTable = sqliteTable("cms_navigation_node", {
 id: text().primaryKey(),
 label: text().notNull(),
 href: text(),
 parentId: text().references(() => cmsNavigationNodeTable.id),
 position: integer().notNull().default(0),
 isExternal: integer({ mode: "boolean" }).default(false),
 createdAt: integer({ mode: "timestamp" }).notNull(),
 updatedAt: integer({ mode: "timestamp" }).notNull(),
});

内容条目表

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


export const cmsEntryTable = sqliteTable("cms_entry", {
 id: text().primaryKey(),
 slug: text().notNull().unique(),
 title: text().notNull(),
 content: text(), // 富文本 HTML
 excerpt: text(),
 status: text({
 enum: ["draft", "published"]
 }).notNull().default("draft"),
 publishedAt: integer({ mode: "timestamp" }),
 createdAt: integer({ mode: "timestamp" }).notNull(),
 updatedAt: integer({ mode: "timestamp" }).notNull(),
});

媒体资源表

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


export const cmsMediaTable = sqliteTable("cms_media", {
 id: text().primaryKey(),
 filename: text().notNull(),
 r2Key: text().notNull(),
 mimeType: text().notNull(),
 size: integer().notNull(),
 width: integer(),
 height: integer(),
 alt: text(),
 createdAt: integer({ mode: "timestamp" }).notNull(),
});

导航管理

导航支持多级嵌套，通过 parentId 实现树形结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


// 查询导航树
export async function getNavigationTree() {
 const db = getDB();
 const nodes = await db.query.cmsNavigationNodeTable.findMany({
 orderBy: (table, { asc }) => [asc(table.position)],
 });

 // 构建树形结构
 const nodeMap = new Map(nodes.map(n => [n.id, { ...n, children: [] }]));
 const roots: typeof nodes = [];

 for (const node of nodeMap.values()) {
 if (node.parentId) {
 nodeMap.get(node.parentId)?.children.push(node);
 } else {
 roots.push(node);
 }
 }

 return roots;
}

拖拽排序

管理后台支持拖拽排序，更新 position 字段：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


export const updateNavigationPositionsAction = actionClient
 .inputSchema(updatePositionsSchema)
 .action(async ({ parsedInput }) => {
 const db = getDB();
 for (const { id, position } of parsedInput.positions) {
 await db
 .update(cmsNavigationNodeTable)
 .set({ position })
 .where(eq(cmsNavigationNodeTable.id, id));
 }
 });

页面内容管理

Tiptap 富文本编辑器

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


// src/app/(admin)/admin/cms/entries/[id]/editor.client.tsx
"use client";

import { useEditor, EditorContent } from "@tiptap/react";
import StarterKit from "@tiptap/starter-kit";
import Image from "@tiptap/extension-image";
import Link from "@tiptap/extension-link";

export function ContentEditor({ content, onChange }) {
 const editor = useEditor({
 extensions: [
 StarterKit,
 Image,
 Link.configure({ openOnClick: false }),
 ],
 content,
 onUpdate: ({ editor }) => {
 onChange(editor.getHTML());
 },
 });

 return (
 <div className="border rounded-lg overflow-hidden">
 <Toolbar editor={editor} />
 <EditorContent editor={editor} className="prose max-w-none p-4" />
 </div>
 );
}

内联编辑

管理员在前台页面可以直接点击内容进行编辑，不需要跳转到后台：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// 检测是否是管理员
const { data: session } = useSessionStore();
const isAdmin = session?.user?.role === "admin";

return (
 <div>
 {isAdmin ? (
 <InlineEditor
 content={entry.content}
 onSave={(html) => updateEntryAction({ id: entry.id, content: html })}
 />
 ) : (
 <div dangerouslySetInnerHTML={{ __html: entry.content }} />
 )}
 </div>
);

媒体资源管理

上传文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


export const uploadCmsMediaAction = actionClient
 .inputSchema(uploadMediaSchema)
 .action(async ({ parsedInput }) => {
 const { file, alt } = parsedInput;
 const { env } = await getCloudflareContext();

 const fileId = createId();
 const ext = file.name.split(".").pop();
 const r2Key = `cms/media/${fileId}.${ext}`;

 // 上传到 R2
 await env.USER_UPLOADS_BUCKET.put(r2Key, await file.arrayBuffer(), {
 httpMetadata: { contentType: file.type },
 });

 // 保存到 DB
 const db = getDB();
 await db.insert(cmsMediaTable).values({
 id: `media_${fileId}`,
 filename: file.name,
 r2Key,
 mimeType: file.type,
 size: file.size,
 alt,
 createdAt: new Date(),
 });
 });

删除文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


export const deleteCmsMediaAction = actionClient
 .inputSchema(z.object({ id: z.string() }))
 .action(async ({ parsedInput }) => {
 const db = getDB();
 const media = await db.query.cmsMediaTable.findFirst({
 where: eq(cmsMediaTable.id, parsedInput.id),
 });

 if (!media) throw new ActionError("NOT_FOUND", "Media not found");

 // 删除 R2 文件
 const { env } = await getCloudflareContext();
 await env.USER_UPLOADS_BUCKET.delete(media.r2Key);

 // 删除 DB 记录
 await db.delete(cmsMediaTable)
 .where(eq(cmsMediaTable.id, parsedInput.id));

 // 清除 KV 缓存
 await invalidateCmsCache();
 });

管理后台

管理后台的路由结构：

1
2
3
4
5
6
7


/admin
 /admin/users # 用户管理
 /admin/users/[id] # 用户详情
 /admin/cms # CMS 概览
 /admin/cms/navigation # 导航管理
 /admin/cms/entries # 内容管理
 /admin/cms/media # 媒体管理

权限控制：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// src/app/(admin)/layout.tsx
export default async function AdminLayout({ children }) {
 const session = await getSessionFromCookie();

 if (!session || session.user.role !== "admin") {
 redirect("/sign-in");
 }

 return <>{children}</>;
}

总结

自建 CMS 的核心模块：

模块	功能
导航管理	树形结构、拖拽排序
内容管理	Tiptap 富文本、内联编辑
媒体管理	R2 存储、图片预览
权限控制	Admin 角色验证

自建 CMS 的好处是完全可控，可以根据业务需求定制功能，而且数据存在自己的 D1，不依赖第三方服务。

React Server Components 下的状态管理策略

Wed, 04 Sep 2024 00:00:00 +0000

用 RSC 之后，我扔掉了大半个 Redux。这篇聊聊在 Server Components 主导的架构里，状态到底该放哪。

背景：RSC 改变了什么

传统 React SPA 里，所有数据都要先 fetch 到客户端，再用状态管理库（Redux、Zustand、React Query）缓存和分发。

RSC 出现后，服务端组件可以直接 await 数据库查询，数据天然在服务端，根本不需要传到客户端再管理。

1
2
3
4
5


传统 SPA：
Browser → API → Redux Store → Component

RSC 架构：
Server Component → DB → HTML → Browser

这意味着大量"服务端数据的客户端缓存"需求直接消失了。

状态分类模型

在 RuiToolAI 项目里，我把状态分成四类：

类型	存放位置	工具
服务端数据	Server Component	直接 await
URL 参数	URL search params	nuqs
客户端全局	内存	Zustand
表单	组件局部	react-hook-form

原则很简单：能放服务端就放服务端，能放 URL 就放 URL，实在不行才用 Zustand。

服务端状态：直接读，不缓存

Server Component 里直接查数据库，不需要任何状态管理库。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


// src/app/(sites)/history/page.tsx
import { getCloudflareContext } from "@opennextjs/cloudflare";
import { drizzle } from "drizzle-orm/d1";
import * as schema from "@/db/schema";
import { eq, desc } from "drizzle-orm";

export default async function HistoryPage() {
 const { env } = await getCloudflareContext();
 const db = drizzle(env.NEXT_TAG_CACHE_D1, { schema });

 // 直接查，不需要 useEffect、不需要 loading state
 const session = await getSessionFromCookie();
 const items = await db
 .select()
 .from(schema.generatedImages)
 .where(eq(schema.generatedImages.userId, session.user.id))
 .orderBy(desc(schema.generatedImages.createdAt))
 .limit(50);

 return <HistoryClient initialItems={items} />;
}

关键点：数据作为 initialItems prop 传给客户端组件，客户端组件只负责交互逻辑（删除、轮询状态更新）。

何时需要 revalidate

Server Component 的数据在请求时是新鲜的，但如果用了 Next.js 缓存，需要手动 revalidate：

1
2
3
4
5
6
7
8
9


// Server Action 里操作完数据后
import { revalidatePath } from "next/cache";

export const deleteImageAction = actionClient
 .inputSchema(deleteImageSchema)
 .action(async ({ parsedInput }) => {
 // ... 删除逻辑
 revalidatePath("/history");
 });

URL 状态：nuqs 管理搜索参数

URL 状态的好处：刷新不丢失、可分享、浏览器前进后退正常工作。

在 RuiToolAI 里，管理后台的筛选条件就放在 URL 里：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// src/app/(admin)/admin/users/page.tsx
import { parseAsString, parseAsInteger, useQueryStates } from "nuqs";

// Server Component 读取 URL 参数
export default async function UsersPage({
 searchParams,
}: {
 searchParams: { page?: string; search?: string };
}) {
 const page = Number(searchParams.page ?? 1);
 const search = searchParams.search ?? "";

 const users = await queryUsers({ page, search });
 return <UsersTable users={users} />;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


// Client Component 更新 URL 参数
"use client";
import { useQueryState } from "nuqs";

function SearchInput() {
 const [search, setSearch] = useQueryState("search", {
 defaultValue: "",
 shallow: false, // 触发服务端重新渲染
 });

 return (
 <input
 value={search}
 onChange={(e) => setSearch(e.target.value)}
 placeholder="搜索用户..."
 />
 );
}

shallow: false 会触发完整的服务端重新渲染，数据自动更新，不需要任何额外的状态管理。

客户端全局状态：Zustand 最小化

Zustand 只用于真正需要跨组件共享的客户端状态。在这个项目里主要是两个：

Session Store

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// src/state/session.ts
import { create } from "zustand";

interface SessionStore {
 user: User | null;
 credits: number;
 setUser: (user: User | null) => void;
 setCredits: (credits: number) => void;
}

export const useSessionStore = create<SessionStore>((set) => ({
 user: null,
 credits: 0,
 setUser: (user) => set({ user }),
 setCredits: (credits) => set({ credits }),
}));

Session 信息在 Layout 里初始化，之后客户端组件直接读取，不需要每次都请求服务端：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


// src/components/session-provider.tsx
"use client";
import { useEffect } from "react";
import { useSessionStore } from "@/state/session";

export function SessionProvider({
 user,
 credits,
}: {
 user: User;
 credits: number;
}) {
 const { setUser, setCredits } = useSessionStore();

 useEffect(() => {
 setUser(user);
 setCredits(credits);
 }, [user, credits]);

 return null;
}

生成任务状态

多任务并发时，需要在生成页面和历史页面之间共享"进行中的任务数量"：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// src/state/generation.ts
import { create } from "zustand";

interface GenerationStore {
 pendingCount: number;
 increment: () => void;
 decrement: () => void;
}

export const useGenerationStore = create<GenerationStore>((set) => ({
 pendingCount: 0,
 increment: () => set((s) => ({ pendingCount: s.pendingCount + 1 })),
 decrement: () =>
 set((s) => ({ pendingCount: Math.max(0, s.pendingCount - 1) })),
}));

表单状态：react-hook-form 局部管理

表单状态是最局部的，用 react-hook-form 管理，不需要提升到全局：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


// src/app/(auth)/sign-up/sign-up.client.tsx
"use client";
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { useAction } from "next-safe-action/hooks";
import { signUpSchema, type SignUpSchema } from "@/schemas/signup.schema";
import { signUpAction } from "./sign-up.actions";

export function SignUpForm() {
 const form = useForm<SignUpSchema>({
 resolver: zodResolver(signUpSchema),
 defaultValues: { email: "", password: "" },
 });

 const { execute, status } = useAction(signUpAction, {
 onSuccess: () => {
 toast.success("注册成功！");
 },
 onError: ({ error }) => {
 toast.error(error.serverError ?? "注册失败");
 },
 });

 return (
 <form onSubmit={form.handleSubmit(execute)}>
 {/* 表单字段 */}
 </form>
 );
}

实战：生成历史页面的状态设计

历史页面是这个项目里状态最复杂的页面，综合用了所有四种状态：

1
2
3
4
5
6
7


服务端状态（initialItems）
 ↓ 传给客户端
客户端局部状态（items: useState）
 ↓ 轮询更新
Server Action（checkImageStatusAction）
 ↓ 完成后
revalidatePath（可选，刷新服务端缓存）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53


// src/app/(sites)/history/client.tsx
"use client";

export function HistoryClient({
 initialItems,
}: {
 initialItems: GeneratedImage[];
}) {
 // 客户端局部状态：从服务端初始值开始
 const [items, setItems] = useState(initialItems);
 const [failedExpanded, setFailedExpanded] = useState(false);

 // 找出所有 processing 的任务
 const processingIds = items
 .filter((item) => item.status === "processing" || item.status === "pending")
 .map((item) => item.id);

 // 轮询逻辑
 const pollAll = useCallback(async () => {
 for (const id of processingIds) {
 const result = await checkImageStatusAction({ id });
 if (result?.data) {
 setItems((prev) =>
 prev.map((item) => (item.id === id ? result.data! : item))
 );
 }
 }
 }, [processingIds]);

 useEffect(() => {
 if (processingIds.length === 0) return;
 pollAll();
 const interval = setInterval(pollAll, 4000);
 // tab 切换回来立即轮询
 const handleVisibility = () => {
 if (document.visibilityState === "visible") pollAll();
 };
 document.addEventListener("visibilitychange", handleVisibility);
 return () => {
 clearInterval(interval);
 document.removeEventListener("visibilitychange", handleVisibility);
 };
 }, [processingIds.length, pollAll]);

 // 删除
 const { execute: deleteImage } = useAction(deleteGeneratedImageAction, {
 onSuccess: ({ input }) => {
 setItems((prev) => prev.filter((item) => item.id !== input.id));
 },
 });

 // 渲染...
}

常见误区

误区 1：在 Server Component 里用 useState

1
2
3
4
5
6
7
8
9


// 错误：Server Component 不能用 hooks
export default async function Page() {
 const [data, setData] = useState(null); // 报错
}

// 正确：直接 await
export default async function Page() {
 const data = await fetchData();
}

误区 2：把服务端数据放进 Zustand

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// 不必要：用 Zustand 缓存服务端数据
const useUserStore = create((set) => ({
 users: [],
 fetchUsers: async () => {
 const users = await fetch("/api/users").then((r) => r.json());
 set({ users });
 },
}));

// 直接在 Server Component 查询
export default async function UsersPage() {
 const users = await db.select().from(schema.users);
 return <UsersList users={users} />;
}

误区 3：URL 状态用 useState 管理

1
2
3
4
5
6
7


// 刷新后丢失
const [filter, setFilter] = useState("all");

// 放 URL 里，刷新不丢失，可分享
const [filter, setFilter] = useQueryState("filter", {
 defaultValue: "all",
});

总结

RSC 架构下的状态管理原则：

服务端数据 → Server Component 直接 await，不需要任何状态库
URL 参数 → nuqs，刷新不丢失，支持分享
客户端全局 → Zustand，只放真正需要跨组件共享的少量状态
表单 → react-hook-form，局部管理

这套分层策略让代码更简单，性能更好，也更容易维护。

参考资源

Next.js Server Actions 最佳实践

Tue, 13 Aug 2024 00:00:00 +0000

为什么用 Server Actions 而不是 API Route

对比项	Server Actions	API Route
类型安全	全栈类型推断	需要手动定义
调用方式	直接调用函数	fetch + JSON
错误处理	统一封装	每个 route 单独处理
认证	在 action 内部处理	在 route 内部处理
代码量	少	多

Server Actions 的最大优势是类型安全：前端调用时，TypeScript 直接知道返回值的类型，不需要手动定义接口。

next-safe-action 封装

直接用 Next.js 原生 Server Actions 缺少统一的错误处理和输入校验。next-safe-action 提供了一个更好的封装：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// src/lib/safe-action.ts
import { createSafeActionClient } from "next-safe-action";

export const actionClient = createSafeActionClient({
 handleServerError(error) {
 if (error instanceof ActionError) {
 return {
 code: error.code,
 message: error.message,
 details: error.details,
 };
 }
 console.error("Unexpected error:", error);
 return {
 code: "INTERNAL_SERVER_ERROR",
 message: "An unexpected error occurred",
 };
 },
});

输入校验

所有 Server Actions 都用 Zod 做输入校验：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// src/schemas/image-gen.schema.ts
import { z } from "zod";

export const generateImageSchema = z.object({
 prompt: z
 .string()
 .min(3, "Prompt must be at least 3 characters")
 .max(1000, "Prompt must be at most 1000 characters"),
});

export type GenerateImageSchema = z.infer<typeof generateImageSchema>;

1
2
3
4
5
6
7
8


// src/sites/image-gen/site.actions.ts
export const generateImageAction = actionClient
 .inputSchema(generateImageSchema)
 .action(async ({ parsedInput }) => {
 // parsedInput 已经过 Zod 校验，类型安全
 const { prompt } = parsedInput;
 // ...
 });

错误处理

统一的错误类型：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// src/lib/action-error.ts
export class ActionError extends Error {
 constructor(
 public code: string,
 message: string,
 public details?: unknown
 ) {
 super(message);
 }
}

在 action 中抛出：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


export const generateImageAction = actionClient
 .inputSchema(generateImageSchema)
 .action(async ({ parsedInput }) => {
 const session = await requireVerifiedEmail();
 if (!session) {
 throw new ActionError("NOT_AUTHORIZED", "You must be signed in");
 }

 const hasCredits = await checkCredits(session.user.id, 10);
 if (!hasCredits) {
 throw new ActionError("PAYMENT_REQUIRED", "Insufficient credits", {
 billingPath: "/dashboard/billing",
 });
 }
 // ...
 });

客户端调用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


"use client";

import { useAction } from "next-safe-action/hooks";
import { generateImageAction } from "./site.actions";

export function ImageGenClient() {
 const { execute, status } = useAction(generateImageAction, {
 onSuccess: ({ data }) => {
 toast.success("Generation started!");
 },
 onError: ({ error }) => {
 const serverError = error.serverError;

 if (serverError?.code === "PAYMENT_REQUIRED") {
 toast.error(serverError.message);
 const billingPath = serverError.details?.billingPath;
 if (billingPath) router.push(billingPath);
 return;
 }

 toast.error(serverError?.message ?? "Something went wrong");
 },
 });

 return (
 <Button
 onClick={() => execute({ prompt })}
 disabled={status === "executing"}
 >
 {status === "executing" ? "Generating..." : "Generate"}
 </Button>
 );
}

AI 任务轮询模式

AI 生成任务需要轮询状态，这是一个常见的异步模式：

提交任务

1
2
3
4
5
6


export const generateImageAction = actionClient
 .inputSchema(generateImageSchema)
 .action(async ({ parsedInput }) => {
 // 扣积分 + 请求大模型 + 存 DB
 return { taskId };
 });

轮询状态

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


export const checkImageStatusAction = actionClient
 .inputSchema(z.object({ taskId: z.string() }))
 .action(async ({ parsedInput }) => {
 const task = await db.query.generatedImageTable.findFirst({
 where: eq(generatedImageTable.id, parsedInput.taskId),
 });

 if (task.status === "completed") {
 return { status: "completed", r2Key: task.r2Key };
 }

 if (task.status === "processing") {
 // 查看最新状态
 const prediction = await CheckPrediction(task.predictionId);
 if (prediction.status === "completed") {
 // 存 R2 + 更新 DB
 return { status: "completed", r2Key };
 }
 }

 return { status: task.status };
 });

前端轮询

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


const { execute: pollStatus } = useAction(checkImageStatusAction, {
 onSuccess: ({ data }) => {
 if (data?.status === "completed") {
 setResult(data);
 clearInterval(intervalRef.current);
 }
 },
});

useEffect(() => {
 if (!taskId) return;
 const interval = setInterval(() => {
 pollStatus({ taskId });
 }, 3000);
 return () => clearInterval(interval);
}, [taskId]);

总结

Server Actions 的最佳实践：

用 next-safe-action 统一封装，避免重复的错误处理代码
所有输入用 Zod 校验，Schema 前后端共享
用 ActionError 统一错误类型，前端可以根据 code 做不同处理
异步任务用"提交 + 轮询"模式，不要在 action 里等待结果

参考资源

Cloudflare Cron 定时任务实战

Wed, 31 Jul 2024 00:00:00 +0000

使用场景

RuiToolAI 的图片生成记录有 7 天有效期，R2 文件会自动删除，但 DB 里的记录不会自动清理。如果不清理，DB 会越来越大，而且历史页面会显示大量"已过期"的空白卡片。

解决方案：用 Cloudflare Cron Triggers 每天定时清理过期记录。

配置 Cron Trigger

在 wrangler.jsonc 中添加：

1
2
3
4
5


{
 "triggers": {
 "crons": ["0 3 * * *"]
 }
}

Cron 表达式格式：分时日月周

表达式	含义
`0 3 * * *`	每天 UTC 凌晨 3 点
`0 /6 * *`	每 6 小时
`0 0 * * 0`	每周日 UTC 0 点
`/5 * * *`	每 5 分钟

实现 scheduled 处理器

在 worker-entrypoint.ts 中添加 scheduled 方法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


export default {
 ...worker,
 async scheduled(
 _event: ScheduledEvent,
 env: Env,
 ctx: ExecutionContext
 ): Promise<void> {
 ctx.waitUntil(cleanupExpiredImageRecords(env));
 },
};

注意：这里用 ctx.waitUntil 是正确的，因为 scheduled 处理器本身就是异步的，不像 HTTP 请求有 CPU 时间限制。

自动清理过期图片记录

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


async function cleanupExpiredImageRecords(env: Env): Promise<void> {
 const { drizzle } = await import("drizzle-orm/d1");
 const schema = await import("./src/db/schema");
 const { generatedImageTable, IMAGE_GEN_STATUS } = schema;
 const { lt, eq, and } = await import("drizzle-orm");

 // 直接用 env.NEXT_TAG_CACHE_D1，不用 getDB()
 // 因为 scheduled 处理器里没有 cloudflare:workers 的全局 env
 const db = drizzle(env.NEXT_TAG_CACHE_D1, { schema });
 const now = new Date();

 const result = await db
 .delete(generatedImageTable)
 .where(
 and(
 eq(generatedImageTable.status, IMAGE_GEN_STATUS.COMPLETED),
 lt(generatedImageTable.expiresAt, now),
 ),
 )
 .returning({ id: generatedImageTable.id });

 console.log(`[cron] Cleaned up ${result.length} expired image records.`);
}

为什么不用 getDB()？

getDB() 内部用了 cloudflare:workers 的 env，这个 env 是通过 Cloudflare 的全局上下文注入的，只在 HTTP 请求处理中可用。scheduled 处理器里需要直接用参数传入的 env。

R2 生命周期规则配合

R2 的生命周期规则负责删除文件，Cron 负责清理 DB 记录，两者配合：

R2 设置（Cloudflare Dashboard）：

1
2
3
4


对象生命周期规则
 规则名称：Delete user uploads after 7 days
 前缀：users/
 操作：7 天后删除对象

时间线：

1
2
3


Day 0：用户生成图片 → 存 R2 → DB 记录 expiresAt = Day 7
Day 7：R2 自动删除文件
Day 7 凌晨 3 点：Cron 清理 DB 中 expiresAt < now 的记录

这样 DB 和 R2 都保持干净。

本地调试

先 build 再用 wrangler dev：

1
2
3
4
5
6
7
8
9


# 方法一：部署到 Cloudflare 后在 Dashboard 手动触发
# Workers → 你的 Worker → Triggers → Cron Triggers → Run

# 方法二：本地 wrangler dev（需要先 build）
pnpm build
npx wrangler dev --port 8787

# 然后触发
curl "http://localhost:8787/__scheduled?cron=0+3+*+*+*"

推荐方法一，更简单，而且可以看到真实的 D1 数据。

总结

Cloudflare Cron Triggers 的使用要点：

在 wrangler.jsonc 的 triggers.crons 中配置 Cron 表达式
在 worker-entrypoint.ts 中实现 scheduled 方法
scheduled 处理器里用参数传入的 env，不用全局 env
配合 R2 生命周期规则，实现文件和 DB 记录的双重清理

参考资源

Stripe 支付集成实战

Thu, 11 Jul 2024 00:00:00 +0000

整体流程

1
2
3
4
5
6
7


用户点击购买
 → 创建 Stripe Checkout Session
 → 跳转到 Stripe 支付页面
 → 用户完成支付
 → Stripe 发送 Webhook 到服务器
 → 服务器验证签名 + 发放积分
 → 用户跳回成功页面

创建 Checkout Session

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


// src/app/(settings)/settings/billing/billing.actions.ts
export const createCheckoutSessionAction = actionClient
 .inputSchema(createCheckoutSchema)
 .action(async ({ parsedInput }) => {
 const session = await requireVerifiedEmail();
 const userId = session.user.id;

 const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

 const checkoutSession = await stripe.checkout.sessions.create({
 mode: "payment",
 payment_method_types: ["card"],
 line_items: [
 {
 price: parsedInput.priceId,
 quantity: 1,
 },
 ],
 success_url: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard/billing?success=true`,
 cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard/billing?canceled=true`,
 metadata: {
 userId,
 priceId: parsedInput.priceId,
 },
 });

 return { url: checkoutSession.url };
 });

前端跳转：

1
2
3
4
5
6
7


const { execute } = useAction(createCheckoutSessionAction, {
 onSuccess: ({ data }) => {
 if (data?.url) {
 window.location.href = data.url;
 }
 },
});

Webhook 处理

Stripe 支付完成后，会向你的服务器发送 Webhook 事件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64


// src/app/api/webhooks/stripe/route.ts
export async function POST(request: Request) {
 const body = await request.text();
 const signature = request.headers.get("stripe-signature")!;

 let event: Stripe.Event;

 try {
 // 验证签名，防止伪造请求
 event = stripe.webhooks.constructEvent(
 body,
 signature,
 process.env.STRIPE_WEBHOOK_SECRET!
 );
 } catch (err) {
 return new Response("Invalid signature", { status: 400 });
 }

 switch (event.type) {
 case "checkout.session.completed": {
 const session = event.data.object as Stripe.CheckoutSession;
 await handleCheckoutCompleted(session);
 break;
 }
 case "charge.refunded": {
 const charge = event.data.object as Stripe.Charge;
 await handleRefund(charge);
 break;
 }
 }

 return new Response("OK", { status: 200 });
}

async function handleCheckoutCompleted(session: Stripe.CheckoutSession) {
 const userId = session.metadata?.userId;
 const priceId = session.metadata?.priceId;

 if (!userId || !priceId) return;

 // 根据 priceId 查找对应的积分数量
 const creditPlan = CREDIT_PLANS.find(p => p.priceId === priceId);
 if (!creditPlan) return;

 const db = getDB();

 // 发放积分
 await db.insert(creditTransactionTable).values({
 id: `txn_${createId()}`,
 userId,
 amount: creditPlan.credits,
 remainingAmount: creditPlan.credits,
 type: CREDIT_TRANSACTION_TYPE.PURCHASE,
 description: `Purchased ${creditPlan.credits} credits`,
 createdAt: new Date(),
 updatedAt: new Date(),
 });

 // 更新用户积分缓存
 await db
 .update(userTable)
 .set({ currentCredits: sql`currentCredits + ${creditPlan.credits}` })
 .where(eq(userTable.id, userId));
}

幂等性处理

Stripe 的 Webhook 可能会重复发送（网络超时重试）。需要保证同一个事件只处理一次。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


async function handleCheckoutCompleted(session: Stripe.CheckoutSession) {
 const db = getDB();

 // 检查是否已经处理过这个 session
 const existing = await db.query.creditTransactionTable.findFirst({
 where: eq(creditTransactionTable.stripeSessionId, session.id),
 });

 if (existing) {
 console.log(`Session ${session.id} already processed, skipping`);
 return;
 }

 // 正常处理...
 await db.insert(creditTransactionTable).values({
 id: `txn_${createId()}`,
 stripeSessionId: session.id, // 记录 session ID
 // ...
 });
}

退款自动化

用户在 Stripe 后台申请退款后，Stripe 会发送 charge.refunded 事件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


async function handleRefund(charge: Stripe.Charge) {
 const sessionId = charge.payment_intent as string;

 // 找到对应的积分记录
 const transaction = await db.query.creditTransactionTable.findFirst({
 where: eq(creditTransactionTable.stripeSessionId, sessionId),
 });

 if (!transaction) return;

 // 扣除积分（不能超过剩余积分）
 const refundCredits = Math.min(
 transaction.remainingAmount,
 transaction.amount
 );

 await db
 .update(creditTransactionTable)
 .set({ remainingAmount: 0 })
 .where(eq(creditTransactionTable.id, transaction.id));

 // 更新用户积分缓存
 await db
 .update(userTable)
 .set({
 currentCredits: sql`MAX(0, currentCredits - ${refundCredits})`,
 })
 .where(eq(userTable.id, transaction.userId));
}

本地调试

本地调试 Webhook 需要用 Stripe CLI 转发事件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 安装 Stripe CLI
brew install stripe/stripe-cli/stripe

# 登录
stripe login

# 转发 Webhook 到本地
stripe listen --forward-to localhost:3000/api/webhooks/stripe

# 触发测试事件
stripe trigger checkout.session.completed

总结

Stripe 集成的关键点：

签名验证：每个 Webhook 都要验证 stripe-signature，防止伪造
幂等性：用 stripeSessionId 去重，防止重复发放积分
退款联动：监听 charge.refunded 事件，自动扣除积分
本地调试：用 Stripe CLI 转发 Webhook 到本地

参考资源

Cloudflare Workers 异步任务处理与 CPU 限制

Wed, 26 Jun 2024 00:00:00 +0000

问题背景

RuiToolAI 的图片生成流程是：

1
2


用户提交 prompt → 调用大模型 → 返回预测 ID
 → 轮询获取结果 → 下载图片 → 存到 R2 → 返回给用户

图片生成需要 10-30 秒，这就需要一个异步任务处理机制。

最初的方案：waitUntil + 后台轮询

最开始，我想用 Cloudflare Workers 的 waitUntil API 在后台轮询：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


// 提交任务
const predictionId = await SubmitImage({ model, prompt });

// 保存任务到 DB
await db.insert(generatedImageTable).values({
 id: taskId,
 userId,
 status: IMAGE_GEN_STATUS.PROCESSING,
 predictionId,
});

// 启动后台轮询
waitUntil(
 runBackgroundPoll({ taskId, userId, predictionId })
);

// 立即返回给前端
return { taskId };

后台轮询函数：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


async function runBackgroundPoll({ taskId, predictionId }) {
 for (let attempt = 1; attempt <= 60; attempt++) {
 await new Promise(r => setTimeout(r, 3000));

 const prediction = await CheckPrediction(predictionId);

 if (prediction.status === "completed") {
 // 下载 + 存 R2 + 更新 DB
 return;
 }
 }
}

为什么失败了

部署上线后，发现任务永远停留在 processing 状态。

根本原因：Cloudflare Workers 的 setTimeout 不会真正 sleep。

Workers 的运行时是 V8 引擎，不是 Node.js。在 Workers 中：

1

await new Promise(r => setTimeout(r, 3000));

这行代码不会等待 3 秒。它几乎立即继续执行，导致 60 次轮询瞬间跑完，Workers 进程结束，但是大模型还没完成。

此外，waitUntil 在 Workers 中也有 CPU 时间限制：

计划	CPU 限制
免费	10ms
付费	30s（wall clock）
`waitUntil`	30s（wall clock）

即使 setTimeout 能正常 sleep，30 秒的 wall clock 限制也不够轮询完 60 次 × 3 秒 = 3 分钟。

最终方案：前端轮询 Server Action

核心思路： 不在后台轮询，而是让前端每次请求时去问一下状态。

1. 提交任务（同步返回）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


export const generateImageAction = actionClient
 .inputSchema(generateImageSchema)
 .action(async ({ parsedInput }) => {
 // 扣积分
 await ensureBillingAccess({ userId, creditsRequired: 10 });

 // 提交到大模型
 const predictionId = await SubmitImage({ model, prompt });

 // 存 DB（状态 = processing）
 await db.insert(generatedImageTable).values({
 id: taskId,
 userId,
 status: IMAGE_GEN_STATUS.PROCESSING,
 predictionId,
 });

 // 立即返回，不等待结果
 return { taskId };
 });

2. 前端轮询

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// 每 3 秒调用一次
useEffect(() => {
 if (!pollingTaskId) return;

 const interval = setInterval(() => {
 executePoll({ taskId: pollingTaskId });
 }, 3000);

 return () => clearInterval(interval);
}, [pollingTaskId]);

3. 状态查询 Action（关键）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


export const checkImageStatusAction = actionClient
 .inputSchema(checkImageStatusSchema)
 .action(async ({ parsedInput }) => {
 const task = await db.query.generatedImageTable.findFirst({
 where: eq(generatedImageTable.id, parsedInput.taskId),
 });

 // 已经完成或失败 → 直接返回
 if (task.status === IMAGE_GEN_STATUS.COMPLETED) {
 return { status: "completed", r2Key: task.r2Key };
 }
 if (task.status === IMAGE_GEN_STATUS.FAILED) {
 return { status: "failed" };
 }

 // 还是在 processing → 查看状态
 const prediction = await CheckPrediction(task.predictionId);

 if (prediction.status === "completed") {
 // 下载图片 + 存 R2 + 更新 DB
 const imageRes = await fetch(prediction.url);
 const buffer = await imageRes.arrayBuffer();
 await env.USER_UPLOADS_BUCKET.put(r2Key, buffer);

 await db.update(generatedImageTable)
 .set({ status: "completed", r2Key })
 .where(eq(generatedImageTable.id, task.id));

 return { status: "completed", r2Key };
 }

 if (prediction.status === "failed") {
 // 退款 + 更新 DB
 await db.update(generatedImageTable)
 .set({ status: "failed" })
 .where(eq(generatedImageTable.id, task.id));

 await addUserCredits(userId, task.creditsCharged);
 return { status: "failed" };
 }

 // 还在处理中
 return { status: "processing" };
 });

用户关闭浏览器后的恢复机制

用户关闭浏览器，再打开时，怎么恢复任务状态？

页面加载时查 DB 里有没有 processing 的任务：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// page.tsx (Server Component)
const processingTask = await db.query.generatedImageTable.findFirst({
 where: and(
 eq(generatedImageTable.userId, userId),
 eq(generatedImageTable.status, IMAGE_GEN_STATUS.PROCESSING),
 ),
 orderBy: (table, { desc }) => [desc(table.createdAt)],
});

// 传给客户端组件
return <ImageGenClient processingTaskId={processingTask?.id} />;

1
2
3
4
5
6


// site.client.tsx
useEffect(() => {
 if (processingTaskId) {
 setPollingTaskId(processingTaskId);
 }
}, []);

历史页面也自动轮询：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// 找到所有 processing 状态的任务
const processingIds = items
 .filter(item => item.status === IMAGE_GEN_STATUS.PROCESSING)
 .map(item => item.id);

// 每 4 秒轮询一次
useEffect(() => {
 if (processingIds.length === 0) return;
 const interval = setInterval(() => {
 for (const id of processingIds) {
 pollStatus({ taskId: id });
 }
 }, 4000);
 return () => clearInterval(interval);
}, [processingIds.length]);

总结

方案演进：

版本	方案	问题
v1	waitUntil + setTimeout	setTimeout 不 sleep
v2	前端轮询 + checkImageStatusAction	每个请求独立，无时间限制

关键设计原则：

每次轮询是一个独立的 Worker 请求，不受 CPU 时间限制
用户关闭浏览器后，DB 保留任务状态，回来后可恢复
历史页面自动轮询所有 processing 任务，不需要手动刷新

参考资源

Cloudflare D1 上实现 FIFO 积分消费系统

Mon, 27 May 2024 00:00:00 +0000

为什么不用简单的余额字段

最简单的积分系统就是一个 currentCredits 字段：

1
2
3
4
5
6
7
8


// 加积分
user.currentCredits += 100;

// 消费
user.currentCredits -= 10;

// 退款
user.currentCredits += 10;

这很简单，但有几个致命问题：

1. 无法审计

用户投诉"我明明有 100 积分怎么没了"，你没法追溯每笔积分的来源和去向。

2. 无法处理积分有效期

如果用户买了两次积分，一次 100（30 天有效期），一次 50（7 天有效期）。消费时应该先扣哪个？简单的余额字段做不到。

3. 退款很难精确

用户买了一次积分，分 5 次消费了，现在要退款——退多少？退哪次买的？

FIFO 消费桶模型

FIFO（First In, First Out）消费桶模型：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


购买 100 积分 → bucket_1: remaining=100
购买 50 积分 → bucket_2: remaining=50

消费 30 积分：
 → bucket_1: remaining = 100 - 30 = 70
 → bucket_2: 不变

消费 80 积分：
 → bucket_1: remaining = 0（用完 70）
 → bucket_2: remaining = 50 - 10 = 40

数据库表设计

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


export const creditTransactionTable = sqliteTable("credit_transaction", {
 id: text().primaryKey(),
 userId: text().notNull().references(() => userTable.id),
 amount: integer().notNull(), // 交易总额
 remainingAmount: integer().notNull(), // 剩余可用积分
 type: text({
 enum: ["PURCHASE", "USAGE", "MONTHLY_REFRESH"]
 }).notNull(),
 description: text(),
 createdAt: integer({ mode: "timestamp" }).notNull(),
 updatedAt: integer({ mode: "timestamp" }).notNull(),
});

三种交易类型：

类型	说明	amount	remainingAmount
PURCHASE	购买积分	100	100（初始全可用）
MONTHLY_REFRESH	月度刷新	50	50
USAGE	消费积分	10	0（记录已消费的量）

消费流程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55


export async function consumeCredits({
 userId,
 amount,
 description,
}: {
 userId: string;
 amount: number;
 description: string;
}) {
 const db = getDB();

 // 1. 查询所有还有剩余积分的桶（按创建时间升序 = FIFO）
 const buckets = await db.query.creditTransactionTable.findMany({
 where: and(
 eq(creditTransactionTable.userId, userId),
 gt(creditTransactionTable.remainingAmount, 0),
 inArray(creditTransactionTable.type, [
 CREDIT_TRANSACTION_TYPE.PURCHASE,
 CREDIT_TRANSACTION_TYPE.MONTHLY_REFRESH,
 ])
 ),
 orderBy: (table, { asc }) => [asc(table.createdAt)],
 });

 // 2. 检查可用积分是否足够
 const totalAvailable = buckets.reduce(
 (sum, b) => sum + b.remainingAmount, 0
 );
 if (totalAvailable < amount) {
 throw new Error("Insufficient credits");
 }

 // 3. 从最早的桶开始扣
 let remaining = amount;
 for (const bucket of buckets) {
 if (remaining <= 0) break;
 const deduct = Math.min(bucket.remainingAmount, remaining);

 await db
 .update(creditTransactionTable)
 .set({ remainingAmount: bucket.remainingAmount - deduct })
 .where(eq(creditTransactionTable.id, bucket.id));

 remaining -= deduct;
 }

 // 4. 记录消费日志
 await logTransaction({
 userId,
 amount,
 description,
 type: CREDIT_TRANSACTION_TYPE.USAGE,
 remainingAmount: 0,
 });
}

退款流程

退款时，按创建时间倒序找到最近被消费过的桶，把积分加回去：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


export async function addUserCredits(userId: string, amount: number) {
 const db = getDB();

 // 找最近的购买记录（remainingAmount < amount 表示被消费过）
 const latestBucket = await db.query.creditTransactionTable.findFirst({
 where: and(
 eq(creditTransactionTable.userId, userId),
 eq(creditTransactionTable.type, CREDIT_TRANSACTION_TYPE.PURCHASE),
 lt(creditTransactionTable.remainingAmount, creditTransactionTable.amount),
 ),
 orderBy: (table, { desc }) => [desc(table.createdAt)],
 });

 if (latestBucket) {
 await db
 .update(creditTransactionTable)
 .set({ remainingAmount: latestBucket.remainingAmount + amount })
 .where(eq(creditTransactionTable.id, latestBucket.id));
 }
}

D1 不支持事务的补偿方案

Cloudflare D1 不支持多语句事务。这意味着"扣积分 + 记录日志"不能原子执行。

补偿方案：先操作，后补偿

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


// 扣积分
await consumeCredits({ userId, amount, description });

// 执行可能失败的操作
try {
 await someExternalApiCall();
} catch (error) {
 // 补偿：退积分
 await addUserCredits(userId, amount);
 await logTransaction({
 userId,
 amount,
 description: "Refund: operation failed",
 type: CREDIT_TRANSACTION_TYPE.PURCHASE,
 remainingAmount: amount,
 });
 throw error;
}

极端情况下（退款也失败），需要人工介入。但实际使用中，结合 Stripe Webhook 的幂等性，风险很低。

总结

FIFO 消费桶模型比简单余额复杂，但提供了：

积分来源和去向的完全可追溯性
积分有效期管理
精确的退款能力
配合补偿方案，在 D1 无事务的环境下也能保证数据一致性

对于 SaaS 产品来说，积分就是钱，这个系统值得花时间好好设计。

参考资源

Lucia Auth 认证体系搭建

Wed, 08 May 2024 00:00:00 +0000

为什么选 Lucia Auth

市面上有很多认证方案：NextAuth、Clerk、Auth0、Supabase Auth……

选 Lucia Auth 的原因：

完全自托管：数据存在自己的 D1，不依赖第三方服务
轻量：只提供核心认证逻辑，不绑定特定数据库
灵活：可以自定义 Session 存储（我们用 KV）
免费：不像 Clerk 按 MAU 收费

邮箱密码登录

注册

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


// src/app/(auth)/sign-up/sign-up.actions.ts
export const signUpAction = actionClient
 .inputSchema(signUpSchema)
 .action(async ({ parsedInput }) => {
 const { email, password } = parsedInput;
 const db = getDB();

 // 检查邮箱是否已注册
 const existing = await db.query.userTable.findFirst({
 where: eq(userTable.email, email.toLowerCase()),
 });
 if (existing) {
 throw new ActionError("CONFLICT", "Email already registered");
 }

 // 哈希密码
 const passwordHash = await hashPassword(password);

 // 创建用户
 const userId = `usr_${createId()}`;
 await db.insert(userTable).values({
 id: userId,
 email: email.toLowerCase(),
 passwordHash,
 role: "user",
 emailVerified: false,
 });

 // 发送验证邮件
 await sendVerificationEmail({ userId, email });

 // 创建 Session
 const sessionId = await createSession(userId);
 await setSessionCookie(sessionId);

 return { success: true };
 });

密码哈希

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


// 使用 Web Crypto API（Workers 兼容）
export async function hashPassword(password: string): Promise<string> {
 const encoder = new TextEncoder();
 const salt = crypto.getRandomValues(new Uint8Array(16));
 const keyMaterial = await crypto.subtle.importKey(
 "raw",
 encoder.encode(password),
 "PBKDF2",
 false,
 ["deriveBits"]
 );
 const hash = await crypto.subtle.deriveBits(
 { name: "PBKDF2", salt, iterations: 100000, hash: "SHA-256" },
 keyMaterial,
 256
 );
 // 拼接 salt + hash，base64 编码存储
 const combined = new Uint8Array(salt.length + hash.byteLength);
 combined.set(salt);
 combined.set(new Uint8Array(hash), salt.length);
 return btoa(String.fromCharCode(...combined));
}

Google OAuth

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53


// src/app/api/auth/google/route.ts
export async function GET() {
 const state = generateState();
 const codeVerifier = generateCodeVerifier();

 const url = google.createAuthorizationURL(state, codeVerifier, [
 "openid",
 "email",
 "profile",
 ]);

 // 存储 state 和 codeVerifier 到 Cookie
 const response = new Response(null, {
 status: 302,
 headers: { Location: url.toString() },
 });
 setCookie(response, "google_oauth_state", state, { httpOnly: true });
 setCookie(response, "google_code_verifier", codeVerifier, { httpOnly: true });

 return response;
}

// src/app/api/auth/google/callback/route.ts
export async function GET(request: Request) {
 const { searchParams } = new URL(request.url);
 const code = searchParams.get("code");
 const state = searchParams.get("state");

 // 验证 state
 const storedState = getCookie(request, "google_oauth_state");
 if (state !== storedState) {
 return new Response("Invalid state", { status: 400 });
 }

 // 换取 token
 const tokens = await google.validateAuthorizationCode(code, codeVerifier);
 const googleUser = await getGoogleUser(tokens.accessToken);

 // 查找或创建用户
 let user = await db.query.userTable.findFirst({
 where: eq(userTable.googleAccountId, googleUser.sub),
 });

 if (!user) {
 user = await createUserFromGoogle(googleUser);
 }

 // 创建 Session
 const sessionId = await createSession(user.id);
 await setSessionCookie(sessionId);

 return redirect("/dashboard");
}

Passkey 无密码登录

Passkey 基于 WebAuthn 标准，用设备的生物识别（Face ID、指纹）替代密码。

注册 Passkey

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


// 1. 服务器生成挑战
export const generatePasskeyRegistrationOptions = actionClient
 .action(async () => {
 const session = await requireVerifiedEmail();
 const options = await generateRegistrationOptions({
 rpName: "RuiToolAI",
 rpID: process.env.NEXT_PUBLIC_APP_DOMAIN!,
 userID: session.user.id,
 userName: session.user.email,
 });
 // 存储 challenge 到 KV
 await kv.put(`passkey_challenge:${session.user.id}`, options.challenge);
 return options;
 });

// 2. 前端调用 WebAuthn API
const credential = await startRegistration(options);

// 3. 服务器验证并保存
export const verifyPasskeyRegistration = actionClient
 .inputSchema(passkeyRegistrationSchema)
 .action(async ({ parsedInput }) => {
 const challenge = await kv.get(`passkey_challenge:${userId}`);
 const verification = await verifyRegistrationResponse({
 response: parsedInput.credential,
 expectedChallenge: challenge,
 expectedOrigin: process.env.NEXT_PUBLIC_APP_URL!,
 });
 if (verification.verified) {
 await db.insert(passkeyTable).values({
 userId,
 credentialId: verification.registrationInfo.credentialID,
 publicKey: verification.registrationInfo.credentialPublicKey,
 });
 }
 });

Session 管理

Session 存储在 Cloudflare KV，而不是 D1，原因是：

KV 读取速度更快（每次请求都要验证 Session）
KV 原生支持 TTL（过期自动删除）
减少 D1 的读取压力

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// src/utils/kv-session.ts
export async function createSession(userId: string): Promise<string> {
 const sessionId = generateId(32);
 const { env } = await getCloudflareContext();

 await env.NEXT_TAG_CACHE_KV.put(
 `session:${sessionId}`,
 JSON.stringify({ userId, createdAt: Date.now() }),
 { expirationTtl: 7 * 24 * 60 * 60 } // 7 天
 );

 return sessionId;
}

export async function getSession(sessionId: string) {
 const { env } = await getCloudflareContext();
 const raw = await env.NEXT_TAG_CACHE_KV.get(`session:${sessionId}`);
 return raw ? JSON.parse(raw) : null;
}

邮箱验证

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


export async function sendVerificationEmail({ userId, email }) {
 const token = generateId(32);
 const db = getDB();

 // 存储验证 token
 await db.insert(emailVerificationTable).values({
 id: `ev_${createId()}`,
 userId,
 token,
 expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 小时
 });

 // 发送邮件
 await sendEmail({
 to: email,
 subject: "Verify your email",
 html: `<a href="${APP_URL}/verify-email?token=${token}">Verify Email</a>`,
 });
}

密码重置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48


// 1. 用户提交邮箱
export const requestPasswordResetAction = actionClient
 .inputSchema(z.object({ email: z.string().email() }))
 .action(async ({ parsedInput }) => {
 const user = await db.query.userTable.findFirst({
 where: eq(userTable.email, parsedInput.email),
 });

 // 不管用户是否存在，都返回成功（防止枚举攻击）
 if (!user) return { success: true };

 const token = generateId(32);
 await db.insert(passwordResetTable).values({
 token,
 userId: user.id,
 expiresAt: new Date(Date.now() + 60 * 60 * 1000), // 1 小时
 });

 await sendPasswordResetEmail({ email: parsedInput.email, token });
 return { success: true };
 });

// 2. 用户点击链接，提交新密码
export const resetPasswordAction = actionClient
 .inputSchema(resetPasswordSchema)
 .action(async ({ parsedInput }) => {
 const { token, newPassword } = parsedInput;

 const resetRecord = await db.query.passwordResetTable.findFirst({
 where: and(
 eq(passwordResetTable.token, token),
 gt(passwordResetTable.expiresAt, new Date()),
 ),
 });

 if (!resetRecord) {
 throw new ActionError("INVALID_TOKEN", "Token is invalid or expired");
 }

 const passwordHash = await hashPassword(newPassword);
 await db.update(userTable)
 .set({ passwordHash })
 .where(eq(userTable.id, resetRecord.userId));

 // 删除 token，防止重复使用
 await db.delete(passwordResetTable)
 .where(eq(passwordResetTable.token, token));
 });

总结

Lucia Auth 的认证体系：

功能	实现方式
邮箱密码	PBKDF2 哈希 + D1 存储
Google OAuth	OAuth 2.0 + PKCE
Passkey	WebAuthn + KV 存储 challenge
Session	KV 存储 + Cookie
邮箱验证	Token + 邮件发送
密码重置	Token + 防枚举设计

参考资源

从零设计 SaaS 多站点架构

Tue, 23 Apr 2024 00:00:00 +0000

问题背景

开发 RuiToolAI 的目标之一，是做一个可复用的 SaaS 模板。每次上线新站，只需要改品牌配置、首页文案、一个主功能模块，以及对应的第三方 API 配置。

这意味着架构需要支持：

多个站点共享同一套代码
每个站点有独立的品牌、文案、功能模块
第三方 API 配置可以按站点隔离

核心设计思路

核心思路是 “配置驱动”：把变化的抽成配置，不变的复用。

1
2
3


共享代码（框架、认证、支付、数据库）
 └── 站点配置（品牌、功能、API）
 └── 具体站点实例（RuiToolAI、xxxxx、...）

目录结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


src/
├── app/ # Next.js App Router
│ ├── (marketing)/ # Landing 页面（共用）
│ ├── (auth)/ # 认证页面（共用）
│ ├── (settings)/ # 设置页面（共用）
│ ├── (admin)/ # 管理后台（共用）
│ └── (sites)/ # 站点功能页面
│ ├── image-gen/ # 图片生成站点
│ └── history/ # 历史记录（共用）
├── sites/ # 站点模块定义
│ ├── image-gen/ # 图片生成模块
│ │ ├── site.config.ts # 站点配置
│ │ ├── site.actions.ts # Server Actions
│ │ └── site.client.tsx # 客户端组件
│ ├── primary/ # 主站点（fallback）
│ └── types.ts # 站点类型定义
├── site/ # 全局站点配置
│ ├── config.ts # 环境变量读取
│ └── marketing.ts # 营销配置
├── components/ # 共享组件
│ ├── landing/ # Landing 组件
│ └── ui/ # UI 组件
└── db/ # 数据库
 └── schema.ts

站点配置系统

类型定义

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// src/sites/types.ts
export interface SiteConfig {
 name: string;
 tagline: string;
 description: string;
 path: string;
 billing: {
 creditsPerUse: number;
 usageDescription: string;
 };
}

站点注册

每个站点模块导出自己的配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// src/sites/image-gen/site.config.ts
export const imageGenSiteConfig: SiteConfig = {
 name: "AI Image Generator",
 tagline: "Turn your ideas into stunning visuals",
 description: "Professional-grade AI image generation",
 path: "/image-gen",
 billing: {
 creditsPerUse: 10,
 usageDescription: "AI image generation",
 },
};

功能模块的插件化

每个站点模块是一套独立的文件，包含：

site.config.ts

站点的元数据配置：

1
2
3
4
5
6
7
8


export const imageGenSiteConfig = {
 name: "AI Image Generator",
 tagline: "Turn your ideas into stunning visuals",
 billing: {
 creditsPerUse: 10,
 usageDescription: "AI image generation",
 },
};

site.actions.ts

站点的 Server Actions（后端逻辑）：

1
2
3
4
5
6
7


"use server";

export const generateImageAction = actionClient
 .inputSchema(generateImageSchema)
 .action(async ({ parsedInput }) => {
 // 扣积分、调用 AI、返回结果
 });

site.client.tsx

站点的前端组件：

1
2
3
4
5


"use client";

export function ImageGenClient({ isLoggedIn }: { isLoggedIn: boolean }) {
 // 输入框、提交按钮、结果展示
}

页面渲染

1
2
3
4
5
6
7
8
9


// src/app/(sites)/image-gen/page.tsx
export default async function ImageGenPage() {
 return (
 <section>
 <h1>{imageGenSiteConfig.name}</h1>
 <ImageGenClient isLoggedIn={Boolean(userId)} />
 </section>
 );
}

品牌配置

品牌相关的配置通过环境变量管理：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// src/site/config.ts
export const siteConfig = {
 branding: {
 siteName: process.env.NEXT_PUBLIC_SITE_NAME ?? "",
 siteDescription: process.env.NEXT_PUBLIC_SITE_DESCRIPTION ?? "",
 socialXUrl: process.env.NEXT_PUBLIC_SOCIAL_X_URL ?? "",
 socialInstagramUrl: process.env.NEXT_PUBLIC_SOCIAL_INSTAGRAM_URL ?? "",
 contactEmail: process.env.NEXT_PUBLIC_CONTACT_EMAIL ?? "",
 },
};

营销页面配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


// src/site/marketing.ts
export const siteMarketing = {
 homeSections: {
 hero: true,
 features: true,
 pricing: true,
 testimonials: true,
 faq: true,
 },
 hero: {
 titleText: "AI-Powered Creative Platform",
 descriptionText: "Generate professional images in seconds",
 },
 features: {
 items: [
 { title: "Multi-Model AI", description: "..." },
 ],
 },
 testimonials: {
 items: [
 { body: "Great tool!", author: { name: "Sarah", avatarUrl: "..." } },
 ],
 },
};

实际案例：从模板到新站点

假设要创建一个叫 “video-gen” 的新站点，用不同的 AI 模型：

步骤 1： 复制 sites/image-gen/ 为 sites/video-gen/

步骤 2： 修改 site.config.ts：

1
2
3
4
5
6
7
8


export const videoGenSiteConfig = {
 name: "video-gen",
 tagline: "Professional design at your fingertips",
 billing: {
 creditsPerUse: 5,
 usageDescription: "video generation",
 },
};

步骤 3： 修改 site.actions.ts 里的 AI 模型配置：

1

const IMAGE_GEN_MODEL = "different-model-v2";

步骤 4： 添加页面路由 src/app/(sites)/video-gen/page.tsx

步骤 5： 修改环境变量，改品牌名和社交链接

完成！ 不需要修改任何共享代码（认证、支付、数据库）。

总结

多站点架构的核心原则：

配置驱动：变的抽成配置，不变的复用
模块化：每个站点功能是独立的模块
环境变量隔离：品牌、API Key 通过环境变量注入
共享基础设施：认证、支付、数据库、CMS 全部共用

这样每次上线新站，只需要改配置 + 一个功能模块，其他全部复用。

TypeScript 全栈类型安全实践

Mon, 15 Apr 2024 00:00:00 +0000

类型安全不只是"不报红线"。这篇聊聊在 RuiToolAI 里如何让类型从数据库一路贯穿到前端 UI。

为什么要全栈类型安全

没有类型安全时，一个字段改名会引发连锁问题：

1
2
3
4
5
6
7


数据库 user.email_address 改名为 user.email
 ↓
API 返回 { emailAddress: string }
 ↓
前端用 user.email 访问 → undefined
 ↓
运行时报错，用户看到空白

有了全栈类型安全，改名时 TypeScript 会在编译时报错，强制你修改所有引用。

数据库层：Drizzle ORM 的类型推导

Drizzle 的最大优势是类型推导。Schema 定义即类型定义：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


// src/db/schema.ts
import { sqliteTable, text, integer, real } from "drizzle-orm/sqlite-core";

export const users = sqliteTable("users", {
 id: text("id").primaryKey(),
 email: text("email").notNull().unique(),
 createdAt: integer("created_at", { mode: "timestamp" })
 .notNull()
 .$defaultFn(() => new Date()),
});

export const generatedImages = sqliteTable("generated_images", {
 id: text("id").primaryKey(),
 userId: text("user_id")
 .notNull()
 .references(() => users.id),
 prompt: text("prompt").notNull(),
 imageUrl: text("image_url"),
 status: text("status", {
 enum: ["pending", "processing", "completed", "failed"],
 })
 .notNull()
 .default("pending"),
 creditsUsed: integer("credits_used").notNull().default(1),
 createdAt: integer("created_at", { mode: "timestamp" })
 .notNull()
 .$defaultFn(() => new Date()),
});

从 Schema 推导类型：

1
2
3
4
5
6
7
8
9


import { InferSelectModel, InferInsertModel } from "drizzle-orm";
import * as schema from "@/db/schema";

// 查询结果类型
export type User = InferSelectModel<typeof schema.users>;
export type GeneratedImage = InferSelectModel<typeof schema.generatedImages>;

// 插入类型（id 和 createdAt 是可选的，因为有默认值）
export type NewGeneratedImage = InferInsertModel<typeof schema.generatedImages>;

查询时类型自动推导：

1
2
3
4
5
6
7
8


const images = await db
 .select()
 .from(schema.generatedImages)
 .where(eq(schema.generatedImages.userId, userId));

// images 的类型是 GeneratedImage[]，不需要手动标注
images[0].status; // 类型是 "pending" | "processing" | "completed" | "failed"
images[0].nonExistent; // TypeScript 报错：Property 'nonExistent' does not exist

API 层：Zod Schema 作为契约

Zod Schema 同时承担两个职责：运行时验证 和 类型定义。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// src/schemas/image-gen.schema.ts
import { z } from "zod";

export const generateImageSchema = z.object({
 prompt: z.string().min(1, "提示词不能为空").max(500, "提示词最多 500 字"),
 style: z.enum(["realistic", "anime", "oil-painting"]).optional(),
 size: z.enum(["512x512", "1024x1024"]).default("1024x1024"),
});

// 从 Schema 推导类型，不需要手动写 interface
export type GenerateImageInput = z.infer<typeof generateImageSchema>;

这样 Schema 和类型永远同步，不会出现"类型说可以，运行时报错"的情况。

Server Actions：next-safe-action 的类型传递

next-safe-action 让 Server Action 的输入输出都有类型：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// src/app/(sites)/image-gen/site.actions.ts
import "server-only";
import { actionClient } from "@/lib/safe-action";
import { generateImageSchema } from "@/schemas/image-gen.schema";

export const generateImageAction = actionClient
 .inputSchema(generateImageSchema)
 .action(async ({ parsedInput }) => {
 // parsedInput 的类型是 GenerateImageInput，自动推导
 const { prompt, style, size } = parsedInput;

 // 返回值类型也会被推导
 return { taskId: "xxx", status: "processing" as const };
 });

客户端调用时，输入输出都有类型检查：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


// src/app/(sites)/image-gen/site.client.tsx
"use client";
import { useAction } from "next-safe-action/hooks";
import { generateImageAction } from "./site.actions";

function ImageGenForm() {
 const { execute, result, status } = useAction(generateImageAction, {
 onSuccess: ({ data }) => {
 // data 的类型是 { taskId: string; status: "processing" }
 console.log(data.taskId); // 有类型提示
 console.log(data.nonExistent); // TypeScript 报错
 },
 });

 return (
 <button
 onClick={() =>
 execute({
 prompt: "a beautiful sunset",
 // size 有默认值，可以不传
 // nonExistent: "xxx" // TypeScript 报错
 })
 }
 >
 生成
 </button>
 );
}

前端：类型从服务端流向客户端

Server Component 查询数据，把结果传给 Client Component：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// src/app/(sites)/history/page.tsx（Server Component）
import type { GeneratedImage } from "@/db/schema";

export default async function HistoryPage() {
 const items: GeneratedImage[] = await db
 .select()
 .from(schema.generatedImages)
 .where(eq(schema.generatedImages.userId, userId));

 // 类型从这里传递给客户端组件
 return <HistoryClient initialItems={items} />;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// src/app/(sites)/history/client.tsx（Client Component）
"use client";
import type { GeneratedImage } from "@/db/schema";

interface HistoryClientProps {
 initialItems: GeneratedImage[];
}

export function HistoryClient({ initialItems }: HistoryClientProps) {
 const [items, setItems] = useState<GeneratedImage[]>(initialItems);

 // items[0].status 的类型是 "pending" | "processing" | "completed" | "failed"
 // 不是 string，可以做精确的条件判断
 const processingItems = items.filter(
 (item) => item.status === "processing" || item.status === "pending"
 );

 return <div>{/* 渲染 */}</div>;
}

环境变量类型安全

环境变量默认是 string | undefined，用之前需要检查。更好的做法是用 Zod 在启动时验证：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// src/env.ts
import { z } from "zod";

const envSchema = z.object({
 // 服务端环境变量
 MODEL_API_KEY: z.string().min(1),
 STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
 STRIPE_WEBHOOK_SECRET: z.string().startsWith("whsec_"),

 // 客户端环境变量（NEXT_PUBLIC_ 前缀）
 NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().startsWith("pk_"),
});

// 启动时验证，缺少必要变量直接报错
export const env = envSchema.parse(process.env);

1
2
3
4


// 使用时有类型，不需要 ! 断言
import { env } from "@/env";

const stripe = new Stripe(env.STRIPE_SECRET_KEY); // string，不是 string | undefined

Cloudflare Bindings 类型生成

Cloudflare Workers 的 Bindings（D1、KV、R2）需要类型定义。不要手写，用 cf-typegen 自动生成：

1

pnpm run cf-typegen

这会根据 wrangler.jsonc 生成 worker-configuration.d.ts：

1
2
3
4
5
6


// worker-configuration.d.ts（自动生成，不要手动编辑）
interface Env {
 NEXT_TAG_CACHE_D1: D1Database;
 NEXT_TAG_CACHE_KV: KVNamespace;
 IMAGES_R2: R2Bucket;
}

在代码里使用时有完整的类型提示：

1
2
3
4
5
6
7


import { getCloudflareContext } from "@opennextjs/cloudflare";

const { env } = await getCloudflareContext();

// env.NEXT_TAG_CACHE_D1 的类型是 D1Database
// env.nonExistent 会报错
const db = drizzle(env.NEXT_TAG_CACHE_D1, { schema });

常用类型工具

从联合类型中提取特定成员

1
2
3


type Status = "pending" | "processing" | "completed" | "failed";
type ActiveStatus = Extract<Status, "pending" | "processing">;
// 等价于 "pending" | "processing"

让某些字段可选

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


type GeneratedImage = {
 id: string;
 prompt: string;
 imageUrl: string | null;
 status: Status;
};

// 创建时 id 由数据库生成，不需要传
type CreateImageInput = Omit<GeneratedImage, "id">;

// 更新时所有字段都是可选的
type UpdateImageInput = Partial<Pick<GeneratedImage, "imageUrl" | "status">>;

函数参数用命名对象

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// ❌ 参数多了容易搞混顺序
function updateImage(id: string, url: string, status: Status) {}

// ✅ 命名对象，顺序无关，可读性好
function updateImage({
 id,
 url,
 status,
}: {
 id: string;
 url: string;
 status: Status;
}) {}

类型守卫

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


function isCompleted(
 image: GeneratedImage
): image is GeneratedImage & { imageUrl: string } {
 return image.status === "completed" && image.imageUrl !== null;
}

// 使用
if (isCompleted(image)) {
 // 这里 image.imageUrl 的类型是 string，不是 string | null
 console.log(image.imageUrl.toUpperCase());
}

总结

全栈类型安全的关键链路：

1
2
3
4
5
6
7


Drizzle Schema → InferSelectModel → 查询结果类型
 ↓
Server Component → props → Client Component
 ↓
Zod Schema → infer → Server Action 输入类型
 ↓
next-safe-action → useAction → 客户端调用类型

核心原则：

Schema 即类型：用 Drizzle 和 Zod 推导类型，不手写 interface
类型向下流动：从数据库 → 服务端 → 客户端，类型一路传递
边界验证：在系统边界（用户输入、外部 API）用 Zod 验证
自动生成：Cloudflare Bindings 类型用 cf-typegen 生成，不手写

参考资源

Serverless 架构下的多数据库选型

Thu, 11 Apr 2024 00:00:00 +0000

为什么需要三种数据库

RuiToolAI 是一个全栈 SaaS 平台，数据需求多种多样：

用户数据、订单、积分流水：需要结构化查询、关联查询
Session、API 缓存、页面缓存：需要极快读写、支持过期时间
用户上传的文件、AI 生成的图片：需要存储大文件、支持 CDN 分发

如果用单一数据库，比如全用 D1，反过来 Session 和缓存会拖慢关系型查询；全用 KV，用户订单这种结构化数据没法做关联查询。

所以选择了 D1 + KV + R2 的组合。

D1：关系型数据库

Cloudflare D1 是基于 SQLite 的 Serverless 关系型数据库，兼容 SQLite 语法。

在 RuiToolAI 中的使用

D1 存储所有结构化数据：

1
2
3
4
5
6
7


user # 用户表
session # Session 表（已迁移到 KV）
credit_transaction # 积分流水表
generated_image # 图片生成记录表
cms_entry # CMS 内容表
cms_navigation_node # CMS 导航表
cms_media # CMS 媒体表

集成方式

使用 Drizzle ORM 操作 D1：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


import { drizzle } from "drizzle-orm/d1";
import { getDB } from "@/db";

const db = getDB();

// 查询
const user = await db.query.userTable.findFirst({
 where: eq(userTable.email, email),
});

// 插入
await db.insert(userTable).values({
 id: `usr_${createId()}`,
 email,
 passwordHash,
 role: "user",
});

局限性

不支持事务：D1 不支持多语句事务，处理退款时要补偿式设计
单文件限制：数据库文件最大 2GB（付费版 10GB）
并发限制：写入并发有限，高并发场景需要设计重试

KV：键值存储

Cloudflare KV 是分布式的键值存储，最终一致性模型，全球秒级同步。

在 RuiToolAI 中的使用

KV 主要用在两个场景：

1. Session 存储

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// 存储 Session
await env.NEXT_TAG_CACHE_KV.put(
 `session:${sessionId}`,
 JSON.stringify(sessionData),
 { expirationTtl: 7 * 24 * 60 * 60 } // 7 天过期
);

// 读取 Session
const raw = await env.NEXT_TAG_CACHE_KV.get(`session:${sessionId}`);
const session = raw ? JSON.parse(raw) : null;

2. Vinext 页面缓存

1
2
3
4


// worker-entrypoint.ts
new KVCacheHandler(env.NEXT_INC_CACHE_KV, {
 appPrefix: VINEXT_CACHE_PREFIX
})

Vinext 框架自动用 KV 做 ISR 缓存，每个页面请求都会先查 KV 是否有缓存。

特点

极快读取：全球边缘节点，毫秒级
最终一致性：写入后最多 60 秒同步到全球
免费额度：每天 10 万次读取，1GB 存储

R2：对象存储

Cloudflare R2 是 S3 兼容的对象存储，最大特点是不收出口流量费。

在 RuiToolAI 中的使用

R2 存储所有用户生成的文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// 存储 AI 生成的图片
await env.USER_UPLOADS_BUCKET.put(r2Key, imageBuffer, {
 httpMetadata: {
 contentType: "image/png",
 contentDisposition: `attachment; filename="${filename}"`,
 },
 customMetadata: {
 prompt: prompt.slice(0, 500),
 generatedBy: userId,
 expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
 },
});

// 读取文件
const object = await env.USER_UPLOADS_BUCKET.get(r2Key);
const buffer = await object.arrayBuffer();

// 删除文件
await env.USER_UPLOADS_BUCKET.delete(r2Key);

生命周期规则

R2 支持自动清理过期文件。在 RuiToolAI 中，设置了 7 天生命周期规则，配合 Cron 定时任务清理 DB 记录：

1
2


R2 规则：uploads/ 前缀，7 天后自动删除
Cron 任务：每天凌晨 3 点，删除 DB 中 expiresAt < now 的记录

选型对比表

特性	D1	KV	R2
数据类型	关系型（SQLite）	键值对	文件/对象
读取速度	快（毫秒级）	极快（毫秒级）	取决于文件大小
一致性	强一致	最终一致	强一致
查询能力	SQL 完整支持	仅 key 查询	前缀/列表
关联查询	支持	不支持	不支持
最大大小	2GB/10GB	1GB（免费）	无限
出口流量费	无	无	无（核心优势）
适合场景	用户数据、订单	缓存、Session	文件存储

实际使用场景

场景一：用户注册

1

用户提交 → D1 INSERT user → KV PUT session → 返回

场景二：AI 图片生成

1

用户提交 → D1 UPDATE credits → D1 INSERT task → Model API → R2 PUT image → D1 UPDATE status

场景三：页面加载

1

用户访问 → KV GET 缓存 → 命中返回 / 未命中 → DB 查询 → 渲染

总结

多数据库不是越多越好，关键是根据数据的访问模式选型：

需要关联查询 → D1
需要极快读写 + 过期 → KV
需要存储大文件 + 免流量 → R2

Cloudflare 的这三件套覆盖了 SaaS 产品 90% 的数据需求，而且全部按量付费，非常适合独立开发者。

参考资源

为什么选择 Cloudflare Workers 而不是传统 VPS

Tue, 26 Mar 2024 00:00:00 +0000

背景

在开发 RuiToolAI 这个全栈 SaaS 项目时，面临一个核心问题：部署在哪里？

传统方案是买一台 VPS（如阿里云、AWS EC2），装 Docker，跑 Node.js 服务。但作为一个独立开发者，我不希望把时间花在运维上。于是我调研了 Cloudflare Workers 这个 Serverless 方案，最终决定把整个项目跑在它上面。

这篇文章就来聊聊为什么做出这个选择，以及实际使用中的经验和教训。

方案对比

传统 VPS 方案

架构：

1

用户 → Nginx → Node.js 服务 → 数据库

优点：

成熟稳定，生态丰富
无运行时限制，可以跑长时间任务
完全控制服务器环境

缺点：

需要自己管理服务器（安全补丁、系统更新、证书续期）
需要自己配置负载均衡和扩容
单地域部署，国内访问国外 VPS 延迟高，反之亦然
费用固定，即使没流量也要付月费

Cloudflare Workers 方案

架构：

1

用户 → Cloudflare 全球边缘节点 → Workers → D1/KV/R2

优点：

全球 330+ 边缘节点，就近响应
零运维，不用管服务器
按量付费，没流量不花钱
D1、KV、R2 原生集成，不需要额外配置连接

缺点：

CPU 时间限制（免费版 10ms，付费版 30s）
不支持 WebSocket 长连接
生态相对较新，部分 npm 包不兼容

Cloudflare Workers 的优势

1. 全球边缘部署，零冷启动

Workers 部署在 Cloudflare 的全球边缘网络上，用户请求会被路由到最近的节点处理。我测试过从国内访问部署在 Workers 上的 RuiToolAI，响应时间在 100-200ms 左右，而同样的应用部署在美西 VPS 上，延迟在 300-500ms。

2. 原生集成 D1/KV/R2

这一点非常重要。传统方案里，你需要：

配置数据库连接字符串
处理连接池
管理文件存储（如 S3 SDK）

而在 Workers 里，这些都是原生 binding：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


const { env } = await getCloudflareContext();

// D1 数据库
const db = getDB();

// KV 缓存
await env.NEXT_INC_CACHE_KV.put(key, value);

// R2 文件存储
await env.USER_UPLOADS_BUCKET.put(key, buffer);

3. GitHub Actions 自动化部署

推送代码到 GitHub → 自动 lint → typecheck → e2e 测试 → 构建 → 部署到 Workers → 执行 D1 迁移。整个过程全自动，不需要手动操作服务器。

成本分析

以 RuiToolAI 为例，目前的使用情况：

服务	免费额度	当前用量	费用
Workers	10 万请求/天	~5000/天	免费
D1	5GB 存储 + 500 万读/天	<1%	免费
KV	1GB 存储 + 10 万读/天	~50%	免费
R2	10GB 存储	<1GB	免费

对比传统 VPS：

最低配置 VPS：$5-10/月
Cloudflare Workers：$0/月（当前用量），流量增长后 $5/月起步

踩过的坑

1. CPU 时间限制导致异步任务失败

最开始我用 waitUntil 在后台轮询 AI 生成结果，但 Workers 的 setTimeout 不会真正 sleep，导致轮询瞬间跑完。

解决方案： 改用前端轮询 Server Action。每次轮询是一个独立请求，不受 30 秒限制。

2. D1 不支持事务

SQLite 在 D1 上不支持多语句事务，这在处理积分退款时很麻烦。

解决方案： 补偿式设计。先扣积分，失败时插入退款记录补充余额。

3. 某些 npm 包不兼容

Workers 不支持 Node.js 原生模块（如 fs、net、crypto 的部分 API）。需要用 Web Crypto API 替代，或者找 Workers 兼容的替代包。

总结

场景	推荐方案
SaaS 产品、API 服务、静态网站	Cloudflare Workers
长时间任务（视频处理、模型训练）	传统 VPS
需要 WebSocket 长连接	传统 VPS
低预算、低流量项目	Cloudflare Workers

对于 RuiToolAI 这种 SaaS 产品，Workers 是完美的选择。零运维、按量付费、全球低延迟，让独立开发者可以专注于产品本身。

RuiToolAI on HanGR的碎碎念

Vinext：用 Vite 替代 Next.js 构建

为什么要迁移到 Vinext

Vinext 是什么

迁移过程

1. 安装 Vinext

2. 替换 package.json 里的脚本

3. 创建 worker-entrypoint.ts

4. 运行兼容性检查

5. 修复兼容性问题

遇到的坑和解决方案

坑 1：waitUntil 里的 setTimeout 不生效

坑 2：某些 npm 包在构建时报错

坑 3：热更新偶尔失效

性能对比

总结

参考资源

GitHub Actions 全自动 CI/CD 流水线

流水线设计

基础 CI 配置

Cloudflare Workers 自动部署

Secrets 管理

生成 Cloudflare API Token

e2e 测试集成

数据库迁移自动化

部署通知

完整流水线示例

常见问题排查

问题 1：pnpm install 很慢

问题 2：Playwright 浏览器每次都重新下载

问题 3：部署失败但没有详细错误信息

问题 4：e2e 测试超时

总结

参考资源

Vitest + Playwright 全栈 e2e 测试实战

测试策略

Vitest 单元测试配置

Playwright e2e 测试配置

测试数据库隔离

SQLite 并发锁问题及解决

问题现象

原因分析

解决方案

为什么之前没问题？

常用测试模式

测试 Server Action

Playwright 测试登录流程

测试需要认证的页面

使用 Page Object Model

CI 里运行测试

总结

参考资源

自建类型安全的多语言 i18n 方案

为什么不用 next-intl

方案设计

Key 的类型定义

翻译文件

服务端使用

客户端使用

添加新翻译的流程

总结

CSS 无限滚动 Marquee 动画实现

效果目标

核心原理

基础实现

无缝循环的关键：复制元素

加入 Tailwind

hover 暂停

两侧渐变遮罩

响应式和暗色模式

完整组件代码

常见问题

Q：滚动速度怎么调？

Q：卡片数量少时循环点很明显怎么办？

Q：移动端性能差怎么办？

Q：能反向滚动吗（从左向右）？

总结

参考资源

Tailwind CSS 暗色模式从零搭建

为什么暗色模式容易搞乱

坑 1：`waitUntil` 里的 setTimeout 不生效