SvelteKit + Cloudflare Workers + Prisma Template

一个现代化的全栈模板，集成了 SvelteKit、Cloudflare Workers、Prisma ORM 和 Tailwind CSS，用于快速构建高性能的全栈应用。

🎯 项目特性

• SvelteKit 5 - 现代 UI 框架，内置路由和 SSR 支持
• Cloudflare Workers - 边缘计算平台，实现全球低延迟部署
• Cloudflare D1 - 分布式 SQLite 数据库
• Prisma ORM - 类型安全的数据库访问层
• Tailwind CSS 4 - 实用优先的 CSS 框架
• TypeScript - 完整的类型安全支持
• Paraglide JS - 国际化支持（i18n）
• Bits UI - 无样式的可访问组件库
• MDsveX - Markdown 和 Svelte 集成

📋 前置要求

• Node.js 18+
• pnpm（推荐） 或 npm/yarn
• Cloudflare 账户（用于部署）

🚀 快速开始

1. 创建项目

# 克隆模板
git clone <template-url> my-app
cd my-app

# 安装依赖
pnpm install

2. 配置 Cloudflare

编辑 wrangler.jsonc，设置你的数据库 ID：

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "sveltekit_template",
      "database_id": "<YOUR_DATABASE_ID>",
      "preview_database_id": "<YOUR_PREVIEW_DATABASE_ID>"
    }
  ]
}

获取数据库 ID 的步骤：

# 创建 D1 数据库
wrangler d1 create sveltekit_template

# 查看已创建的数据库
wrangler d1 list

3. 初始化数据库

# 生成初始迁移文件
pnpm run db:init

# 本地执行迁移
pnpm run db:local

# 远程执行迁移（生产环境）
pnpm run db:remote

4. 启动开发服务器

pnpm run dev

访问 http://localhost:5173 查看你的应用。

📁 项目结构

.
├── src/
│   ├── routes/              # SvelteKit 路由
│   ├── lib/
│   │   ├── components/      # Svelte 组件
│   │   ├── generated/       # 生成的代码（Prisma、Paraglide）
│   │   ├── utils.ts         # 工具函数
│   │   ├── prisma.ts        # Prisma 客户端初始化
│   │   └── paraglide/       # 国际化配置
│   ├── hooks.server.ts      # 服务器钩子
│   ├── app.html             # HTML 模板
│   └── app.css              # 全局样式
├── prisma/
│   ├── schema.prisma        # 数据库 Schema
│   └── dev.db               # 本地开发数据库（SQLite）
├── migrations/              # 数据库迁移脚本
├── public/                  # 静态资源
├── package.json             # 项目依赖
├── svelte.config.js         # SvelteKit 配置
├── vite.config.ts           # Vite 配置
├── wrangler.jsonc           # Cloudflare Workers 配置
└── tailwind.config.ts       # Tailwind CSS 配置

🔧 开发命令

# 启动开发服务器
pnpm run dev

# 构建生产版本
pnpm run build

# 预览构建结果
pnpm run preview

# 代码检查
pnpm run check
pnpm run check:watch

# 代码检查和修复
pnpm run lint

# 生成 Prisma 类型
pnpm run db:types

# 初始化数据库迁移
pnpm run db:init

# 本地执行数据库迁移
pnpm run db:local

# 远程执行数据库迁移
pnpm run db:remote

📊 数据库使用

定义 Schema

编辑 prisma/schema.prisma：

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String?
  posts     String
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String
  userId    Int
  createdAt DateTime @default(now())
}

生成迁移

# 修改 schema 后，生成迁移脚本
pnpm run db:init

在服务器端使用 Prisma

在 +server.ts 或其他服务器文件中：

import type { RequestHandler } from "@sveltejs/kit";
import { getPrismaClient } from "$lib/prisma";

export const GET: RequestHandler = async ({ platform }) => {
  const prisma = getPrismaClient(platform!.env);

  const users = await prisma.user.findMany();

  return Response.json(users);
};

在客户端使用数据

利用 SvelteKit 的 load 函数从 API 获取数据：

// src/routes/+page.ts
import type { PageLoad } from "./$types";

export const load: PageLoad = async ({ fetch }) => {
  const response = await fetch("/api/users");
  const users = await response.json();

  return { users };
};

然后在页面中使用：

<!-- src/routes/+page.svelte -->
<script lang="ts">
  import type { PageData } from './$types';

  export let data: PageData;
</script>

<h1>Users</h1>
<ul>
  {#each data.users as user (user.id)}
    <li>{user.name} ({user.email})</li>
  {/each}
</ul>

🌍 国际化 (i18n)

项目使用 Paraglide JS 实现国际化，支持多语言。

语言文件

语言翻译文件位于 messages/ 目录：

messages/
├── en.json    # 英文
├── es.json    # 西班牙文
└── zh.json    # 中文

示例 messages/en.json：

{
  "greeting": "Hello, {name}!",
  "welcome": "Welcome to our app"
}

在组件中使用

<script>
  import * as m from '$lib/paraglide/messages';
</script>

<h1>{m.greeting({ name: 'John' })}</h1>
<p>{m.welcome()}</p>

获取当前语言

import { getLanguageTag } from "$lib/paraglide/runtime";

const currentLang = getLanguageTag(); // 'en', 'es', 'zh'

🎨 组件库

项目使用 Bits UI 提供无样式的可访问组件，你可以根据需要自定义样式。

可用组件

• Accordion - src/lib/components/ui/accordion/
• Avatar - src/lib/components/ui/avatar/
• Aspect Ratio - src/lib/components/ui/aspect-ratio/

使用示例

<script>
  import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '$lib/components/ui/accordion';
</script>

<Accordion>
  <AccordionItem value="item-1">
    <AccordionTrigger>Section 1</AccordionTrigger>
    <AccordionContent>Content for section 1</AccordionContent>
  </AccordionItem>
</Accordion>

🚢 部署

部署到 Cloudflare

# 构建项目
pnpm run build

# 部署到 Cloudflare
wrangler deploy

部署前检查清单

• 在 wrangler.jsonc 中设置正确的数据库 ID
• 运行 pnpm run check 检查代码
• 运行 pnpm run build 构建生产版本
• 确保所有迁移已在远程数据库上执行
• 检查环境变量配置

🔐 环境变量

创建 .env.local 文件（本地开发）：

# 仅在需要时添加敏感信息
# 大部分配置应在 wrangler.jsonc 中进行

在 wrangler.jsonc 中定义变量：

{
  "vars": {
    "API_URL": "https://api.example.com",
    "APP_NAME": "My App"
  }
}

在代码中访问环境变量：

export const load = async ({ platform }) => {
  const apiUrl = platform?.env.API_URL;
  return { apiUrl };
};

📝 API 路由示例

创建 API 端点

创建 src/routes/api/users/+server.ts：

import type { RequestHandler } from "@sveltejs/kit";
import { getPrismaClient } from "$lib/prisma";
import { json } from "@sveltejs/kit";

export const GET: RequestHandler = async ({ platform }) => {
  const prisma = getPrismaClient(platform!.env);
  const users = await prisma.user.findMany();
  return json(users);
};

export const POST: RequestHandler = async ({ request, platform }) => {
  const prisma = getPrismaClient(platform!.env);
  const data = await request.json();

  const user = await prisma.user.create({
    data: {
      email: data.email,
      name: data.name,
      posts: data.posts || "",
    },
  });

  return json(user, { status: 201 });
};

🧪 测试

# 运行 svelte-check 进行类型检查
pnpm run check

# 监听模式下进行类型检查
pnpm run check:watch

📦 依赖说明

🛠️ 常见问题

Q: 如何添加新的数据库模型？

A: 编辑 prisma/schema.prisma，添加新的 model，然后运行 pnpm run db:init 生成迁移脚本。

Q: 如何处理数据库迁移冲突？

A: 如果迁移脚本有冲突，手动编辑 migrations/ 目录中的 SQL 文件，确保语法正确，然后重新执行迁移。

Q: 本地开发时如何使用 D1？

A: 运行 pnpm run dev 时，Wrangler 会自动在本地启动 D1 模拟器。数据存储在 .wrangler/ 目录中。

Q: 如何在组件中使用 TypeScript？

A: 在 <script lang="ts"> 标签中编写代码，SvelteKit 会自动支持 TypeScript。

Q: 如何添加新的国际化语言？

A: 在 messages/ 目录中创建新的语言文件（例如 fr.json），按照已有文件的结构填写翻译内容。Paraglide 会自动识别。

📚 相关资源

• SvelteKit 文档
• Cloudflare Workers 文档
• Cloudflare D1 文档
• Prisma 文档
• Tailwind CSS 文档
• Paraglide JS 文档

📄 许可证

MIT

🤝 贡献

欢迎提交 Issue 和 Pull Request！

提示：这是一个模板项目，请根据你的需求进行自定义和扩展。