vite-flare-starter

Vite Flare 启动模板

克隆并配置开箱即用的 Cloudflare 启动模板，将其变为独立项目。生成完全重新品牌化、可部署的全栈应用。

技术栈

层	技术	版本
前端	React、Vite、Tailwind CSS、shadcn/ui	19、6.x、v4、latest
后端	Hono（运行于 Cloudflare Workers）	4.x
数据库	D1（边缘 SQLite）+ Drizzle ORM	0.38+
身份验证	better-auth（Google OAuth + 邮箱/密码）	latest
存储	R2（兼容 S3 的对象存储）	—
AI	Workers AI 绑定	—
数据获取	TanStack Query	v5

Cloudflare 绑定

绑定	类型	用途
DB	D1 数据库	应用主数据库
AVATARS	R2 存储桶	用户头像存储
FILES	R2 存储桶	常规文件上传
AI	Workers AI	AI 模型推理

项目结构

src/
├── client/                 # React frontend
│   ├── components/         # UI components
│   ├── hooks/              # Custom hooks + TanStack Query
│   ├── pages/              # Route pages
│   ├── lib/                # Utilities (auth client, etc.)
│   └── main.tsx            # App entry point
├── server/                 # Hono backend
│   ├── index.ts            # Worker entry point
│   ├── routes/             # API routes
│   ├── middleware/          # Auth, CORS, etc.
│   └── db/                 # Drizzle schema + queries
└── shared/                 # Shared types between client/server

关键命令

命令	用途
pnpm dev	启动本地开发服务
pnpm build	生产构建
pnpm deploy	部署到 Cloudflare
pnpm db:migrate:local	在本地应用迁移
pnpm db:migrate:remote	将迁移应用到生产环境
pnpm db:generate	根据架构变更生成迁移

工作流

步骤 1：收集项目信息

询问：

必填	可选
项目名称（kebab-case）	管理员邮箱
描述（1 句话）	Google OAuth 凭据
Cloudflare 账户	自定义域名

步骤 2：克隆并配置

2a. 克隆并清理

git clone https://github.com/jezweb/vite-flare-starter.git PROJECT_DIR --depth 1
cd PROJECT_DIR
rm -rf .git
git init

2b. 查找并替换目标

在以下位置将 vite-flare-starter 替换为项目名称：

文件	目标	替换为
wrangler.jsonc	"vite-flare-starter"（Worker 名称）	"PROJECT_NAME"
wrangler.jsonc	vite-flare-starter-db	PROJECT_NAME-db
wrangler.jsonc	vite-flare-starter-avatars	PROJECT_NAME-avatars
wrangler.jsonc	vite-flare-starter-files	PROJECT_NAME-files
package.json	"name": "vite-flare-starter"	"name": "PROJECT_NAME"
package.json	vite-flare-starter-db	PROJECT_NAME-db
index.html	<title> 内容	应用显示名称（标题格式）

同时，在 wrangler.jsonc 中：

• 移除硬编码的 account_id 行（让 wrangler 提示输入，或使用环境变量）
• 将 database_id 值替换为 REPLACE_WITH_YOUR_DATABASE_ID

将 package.json 版本重置为 "0.1.0"。

使用 Edit 工具进行替换（优先于 sed，以避免 macOS/GNU 差异）。

2c. 生成身份验证密钥

BETTER_AUTH_SECRET=$(openssl rand -hex 32 2>/dev/null || python3 -c "import secrets; print(secrets.token_hex(32))")

2d. 创建 .dev.vars

转换 kebab-case 项目名称：my-cool-app 转换为显示名称 My Cool App，ID 为 my_cool_app。

# Local Development Environment Variables
# DO NOT COMMIT THIS FILE TO GIT

# Authentication (better-auth)
BETTER_AUTH_SECRET=<generated>
BETTER_AUTH_URL=http://localhost:5173

# Google OAuth (optional)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

# Email Auth Control (disabled by default)
# ENABLE_EMAIL_LOGIN=true
# ENABLE_EMAIL_SIGNUP=true

# Application Configuration
APP_NAME=<Display Name>
VITE_APP_NAME=<Display Name>
VITE_APP_ID=<app_id>
VITE_TOKEN_PREFIX=<app_id>_
VITE_GITHUB_URL=
VITE_FOOTER_TEXT=

NODE_ENV=development

2e. 创建 Cloudflare 资源（可选）

npx wrangler d1 create PROJECT_NAME-db
# Extract database_id from output, update wrangler.jsonc

npx wrangler r2 bucket create PROJECT_NAME-avatars
npx wrangler r2 bucket create PROJECT_NAME-files

2f. 安装并迁移

pnpm install
pnpm run db:migrate:local

2g. 初始提交

git add -A
git commit -m "Initial commit from vite-flare-starter"

步骤 3：手动配置

1. Google OAuth（如需使用）：前往 Google Cloud Console，创建 OAuth 2.0 客户端 ID，添加重定向 URI http://localhost:5173/api/auth/callback/google，将客户端 ID 和密钥复制到 .dev.vars
2. 网站图标：替换 public/favicon.svg
3. CLAUDE.md：更新项目描述，移除 vite-flare-starter 相关内容
4. index.html：更新 <title> 和 meta description

步骤 4：本地验证

pnpm dev

检查：访问 http://localhost:5173 后页面能正常加载、显示你的应用名称，并且注册/登录功能正常（如已配置 OAuth）。

步骤 5：部署到生产环境

# Set production secrets
openssl rand -base64 32 | npx wrangler secret put BETTER_AUTH_SECRET
echo "https://PROJECT_NAME.SUBDOMAIN.workers.dev" | npx wrangler secret put BETTER_AUTH_URL
echo "http://localhost:5173,https://PROJECT_NAME.SUBDOMAIN.workers.dev" | npx wrangler secret put TRUSTED_ORIGINS

# If using Google OAuth
echo "your-client-id" | npx wrangler secret put GOOGLE_CLIENT_ID
echo "your-client-secret" | npx wrangler secret put GOOGLE_CLIENT_SECRET

# Migrate remote database
pnpm run db:migrate:remote

# Build and deploy
pnpm run build && pnpm run deploy

重要：首次部署后，将 BETTER_AUTH_URL 更新为实际的 Worker URL。将生产环境 URL 添加到 Google OAuth 重定向 URI 中。

安全标识

请修改以下所有内容，避免攻击者识别出你的网站使用了此启动模板：

位置	默认值	修改方法
页面标题	"Vite Flare Starter"	index.html
UI 中的应用名称	"Vite Flare Starter"	VITE_APP_NAME 环境变量
localStorage 键	vite-flare-starter-theme	VITE_APP_ID 环境变量
API 令牌	vfs_ 前缀	VITE_TOKEN_PREFIX 环境变量
GitHub 链接	启动模板仓库	VITE_GITHUB_URL（设为空即可隐藏）
Worker 名称	vite-flare-starter	wrangler.jsonc
数据库名称	vite-flare-starter-db	wrangler.jsonc
R2 存储桶	vite-flare-starter-*	wrangler.jsonc

环境变量

品牌信息（VITE_ 前缀的变量可在前端使用）

变量	用途	示例
VITE_APP_NAME	UI 中显示的名称	"My Cool App"
VITE_APP_ID	localStorage 前缀、Sentry	"mycoolapp"
VITE_TOKEN_PREFIX	API 令牌前缀	"mca_"
VITE_GITHUB_URL	GitHub 链接（为空则隐藏）	""
VITE_FOOTER_TEXT	页脚版权文本	"2026 My Company"
APP_NAME	服务端应用名称	"My Cool App"

身份验证

变量	用途	备注
BETTER_AUTH_SECRET	会话加密	openssl rand -hex 32
BETTER_AUTH_URL	身份验证基础 URL	必须与实际 URL 完全一致
TRUSTED_ORIGINS	允许的来源	以逗号分隔，包含 localhost 和生产环境地址
GOOGLE_CLIENT_ID	Google OAuth	从 Google Cloud Console 获取
GOOGLE_CLIENT_SECRET	Google OAuth	从 Google Cloud Console 获取
ENABLE_EMAIL_LOGIN	启用邮箱/密码登录	设为 "true" 即可启用
ENABLE_EMAIL_SIGNUP	启用邮箱注册	需要启用 ENABLE_EMAIL_LOGIN

邮件（可选）

变量	用途	备注
EMAIL_FROM	发件人地址	用于验证和重置密码
EMAIL_API_KEY	邮件服务 API 密钥	推荐使用 Resend

常见自定义操作

添加新的数据库表

1. 在 src/server/db/schema.ts 中添加架构
2. 生成迁移：pnpm db:generate
3. 在本地应用：pnpm db:migrate:local
4. 在生产环境应用：pnpm db:migrate:remote

添加新的 API 路由

1. 在 src/server/routes/ 中创建路由文件
2. 在 src/server/index.ts 中注册
3. 在 src/client/hooks/ 中添加 TanStack Query hook

更改身份验证提供方

编辑 src/server/auth.ts：将提供方添加到 socialProviders，将凭据添加到 .dev.vars 和生产环境密钥中，并更新客户端登录按钮。

功能开关

通过环境变量控制功能：VITE_FEATURE_STYLE_GUIDE=true、VITE_FEATURE_COMPONENTS=true。在 src/client/lib/features.ts 中添加你自己的功能开关。

故障排除

症状	原因	解决方法
身份验证静默重定向到主页	缺少 TRUSTED_ORIGINS	设置 TRUSTED_ORIGINS，包含所有有效 URL
部署时提示 "Not authorized"	account_id 错误	从 wrangler.jsonc 中移除 account_id，或设置为你自己的值
数据库出现 500 错误	缺少迁移	运行 pnpm db:migrate:local 和 pnpm db:migrate:remote
localStorage 显示 "vite-flare-starter"	缺少 VITE_APP_ID	在 .dev.vars 中设置 VITE_APP_ID=yourapp
仅在生产环境中身份验证失败	BETTER_AUTH_URL 不匹配	必须与实际 Worker URL 完全一致（使用 https，不带末尾斜杠）
使用 Google 登录时提示 "redirect_uri_mismatch"	缺少 OAuth 重定向 URI	将生产环境 URL 添加到 Google Cloud Console 的 OAuth 重定向 URI 中
密钥变更未生效	尚未重新部署	wrangler secret put 不会重新部署。之后运行 pnpm deploy

生产部署检查清单

• 已设置 BETTER_AUTH_SECRET（与开发环境不同！）
• BETTER_AUTH_URL 与实际 Worker URL 相符
• TRUSTED_ORIGINS 包含所有有效 URL
• Google OAuth 重定向 URI 包含生产环境 URL
• 远程数据库已迁移（pnpm db:migrate:remote）
• 配置文件中没有 vite-flare-starter 引用
• 已替换网站图标
• 已更新 CLAUDE.md
• 未提交 .dev.vars（检查 .gitignore）