Better-T-Stack

概述

CLI 会验证选项组合以确保生成的项目能正常工作。以下是关键的兼容性规则和限制。

数据库与 ORM 兼容性

必需组合

数据库	兼容的 ORM	说明
`sqlite`	`drizzle`, `prisma`	轻量级、基于文件的数据库
`postgres`	`drizzle`, `prisma`	高级关系型数据库
`mysql`	`drizzle`, `prisma`	传统关系型数据库
`mongodb`	`mongoose`, `prisma`	文档数据库，需要特定 ORM
`none`	`none`	无数据库设置

限制

MongoDB + Drizzle: ❌ 不支持 - Drizzle 不支持 MongoDB
有数据库无 ORM: ❌ 不支持 - 数据库需要 ORM 进行代码生成
有 ORM 无数据库: ❌ 不支持 - ORM 需要数据库目标

# ❌ 无效 - MongoDB 与 Drizzle 组合
create-better-t-stack --database mongodb --orm drizzle

# ✅ 有效 - MongoDB 与 Mongoose 组合
create-better-t-stack --database mongodb --orm mongoose

后端与运行时兼容性

Cloudflare Workers 限制

Cloudflare Workers 有特定的兼容性要求：

组件	要求	原因
后端	必须是 `hono`	只有 Hono 支持 Workers 运行时
ORM	必须是 `drizzle` 或 `prisma`	Workers 支持 Drizzle 和 Prisma；不支持 Mongoose
数据库	不能是 `mongodb`	MongoDB 需要 Prisma/Mongoose
数据库设置	不能是 `docker`	Workers 是无服务器的，不支持 Docker

# ❌ 无效 - Workers 与 Express 组合
create-better-t-stack --runtime workers --backend express

# ✅ 有效 - Workers 与 Hono 组合
create-better-t-stack --runtime workers --backend hono --database sqlite --orm drizzle --db-setup d1

# ✅ 同样有效 - Workers 与 Prisma (D1) 组合
create-better-t-stack --runtime workers --backend hono --database sqlite --orm prisma --db-setup d1

后端预设

Convex 后端

使用 --backend convex 时，以下选项会自动设置：

--auth clerk（如果选择了兼容的前端，否则为 none）
--database none（Convex 提供数据库）
--orm none（Convex 提供数据层）
--api none（Convex 提供 API）
--runtime none（Convex 管理运行时）
--db-setup none（Convex 管理托管）
--examples todo（Todo 示例与 Convex 配合使用）

注意： Convex 支持与兼容前端（React 框架、Next.js、TanStack Start 和原生框架）的 Clerk 身份验证。Nuxt、Svelte 和 Solid 与 Clerk 不兼容。

无后端

使用 --backend none 时，以下选项会自动设置：

--auth none（无后端用于身份验证）
--database none（无后端用于数据库）
--orm none（无数据库）
--api none（无后端用于 API）
--runtime none（无后端运行）
--db-setup none（无数据库托管）
--examples none（示例需要后端）

前端与 API 兼容性

API 框架支持

前端	tRPC 支持	oRPC 支持	说明
`tanstack-router`	✅	✅	完全支持
`react-router`	✅	✅	完全支持
`tanstack-start`	✅	✅	完全支持
`next`	✅	✅	完全支持
`nuxt`	❌	✅	不支持 tRPC
`svelte`	❌	✅	不支持 tRPC
`solid`	❌	✅	不支持 tRPC
原生框架	✅	✅	完全支持

# ❌ 无效 - Nuxt 与 tRPC 组合
create-better-t-stack --frontend nuxt --api trpc

# ✅ 有效 - Nuxt 与 oRPC 组合
create-better-t-stack --frontend nuxt --api orpc

前端限制

多个 Web 前端: ❌ 只允许一个 Web 框架
多个原生前端: ❌ 只允许一个原生框架
Web + 原生: ✅ 允许一个 Web 和一个原生框架

# ❌ 无效 - 多个 Web 前端
create-better-t-stack --frontend next tanstack-router

# ✅ 有效 - Web + 原生
create-better-t-stack --frontend next native-nativewind

数据库设置兼容性

提供商要求

设置提供商	必需数据库	说明
`turso`	`sqlite`	分布式 SQLite；与 Drizzle 和 Prisma 配合使用
`d1`	`sqlite`	Cloudflare D1（需要 Workers 运行时）；与 Drizzle 和 Prisma 配合使用
`neon`	`postgres`	无服务器 PostgreSQL
`supabase`	`postgres`	具有附加功能的 PostgreSQL
`prisma-postgres`	`postgres`	通过 Prisma 管理的 PostgreSQL
`mongodb-atlas`	`mongodb`	托管的 MongoDB
`docker`	`postgres`, `mysql`, `mongodb`	与 `sqlite` 或 Workers 不兼容

特殊情况

Cloudflare D1

需要 --database sqlite
需要 --runtime workers
需要 --backend hono

Docker 设置

不能与 sqlite 一起使用（基于文件的数据库）
不能与 workers 运行时一起使用（无服务器环境）

附加功能兼容性

PWA 支持

需要 Web 前端
兼容的前端：tanstack-router, react-router, next, solid
不与纯原生项目兼容

Tauri（桌面应用）

需要 Web 前端
兼容的前端：tanstack-router, react-router, nuxt, svelte, solid, next
不能与原生框架组合使用

Web 部署

--web-deploy wrangler 需要 Web 前端
不能用于纯原生项目

身份验证要求

Better-Auth 要求

Better-Auth 身份验证需要：

后端框架（不能是 none）
数据库（不能是 none）
ORM（不能是 none）

Clerk 要求

Clerk 身份验证需要：

Convex 后端（--backend convex）
兼容的前端（React 框架、Next.js、TanStack Start、原生框架）
不与 Nuxt、Svelte 或 Solid 兼容

# ❌ 无效 - Better-Auth 无数据库
create-better-t-stack --auth better-auth --database none

# ✅ 有效 - Better-Auth 完整技术栈
create-better-t-stack --auth better-auth --database postgres --orm drizzle --backend hono

# ✅ 有效 - Clerk 与 Convex 组合
create-better-t-stack --auth clerk --backend convex --frontend tanstack-router

# ❌ 无效 - Clerk 无 Convex
create-better-t-stack --auth clerk --backend hono

示例兼容性

Todo 示例

存在后端时需要数据库（Convex 除外）
不能与 --backend none 和 --database none 一起使用

AI 示例

不与 --backend elysia 兼容
不与 --frontend solid 兼容

常见错误消息

"Mongoose ORM 需要 MongoDB 数据库"

# 通过使用 MongoDB 修复
create-better-t-stack --database mongodb --orm mongoose

"Cloudflare Workers 运行时仅支持 Hono 后端"

# 通过使用 Hono 修复
create-better-t-stack --runtime workers --backend hono

"不能选择多个 Web 框架"

# 通过选择一个 Web 框架修复
create-better-t-stack --frontend tanstack-router

"身份验证需要数据库"

# 通过为 Better-Auth 添加数据库修复
create-better-t-stack --auth better-auth --database postgres --orm drizzle

# 或使用 Clerk 与 Convex（不需要数据库）
create-better-t-stack --auth clerk --backend convex

验证策略

CLI 按以下顺序验证兼容性：

基本验证：必需参数、有效的枚举值
组合验证：数据库 + ORM、后端 + 运行时兼容性
功能验证：身份验证要求、附加功能兼容性
示例验证：示例 + 技术栈兼容性

了解这些规则有助于您创建有效的配置，并在 CLI 报告兼容性错误时进行故障排除。

兼容性规则

On this page