常见问题解答

这里汇总了开发者在安装、配置和使用 ShipSaaS 过程中最常见的问题。

核心概念与技术栈

什么是 ShipSaaS？

ShipSaaS 是一个极速、轻量且高度模块化的 SaaS 模板，它基于 NextJS 框架（ShipStack）构建，并专为 Cloudflare Workers / Pages 边缘网络优化。它集成了现代 SaaS 应用所需的所有核心功能（身份验证、数据库、订阅支付、邮件服务、AI 推理等），可帮助您在一小时内上线自己的付费应用。

为什么选择 NextJS 和 Cloudflare Workers？

• NextJS (ShipStack) 提供了企业级的控制反转（IoC）与依赖注入（DI）机制，使得项目架构高度模块化和松耦合，拥有极佳的类型安全与可扩展性，相比于传统的 T-based 架构（如 TanStack Start），在应对复杂业务逻辑时更加游刃有余。
• Cloudflare Workers 具有零冷启动、全球边缘分布、无服务器托管以及极其慷慨的免费额度。结合 D1 (SQLite) 和 R2 (对象存储)，您可以零成本启动您的项目。

数据库与存储问题

如何在本地连接 Cloudflare D1 数据库？

在本地运行时，Wrangler 会自动在本地创建一个 SQLite 文件来模拟 D1 数据库。您不需要进行复杂的配置。只需要在初始化项目时，运行迁移命令将其应用到本地模拟器即可：

bun run db:bootstrap:local

本地模拟的数据库数据保存在哪里？

本地模拟的 D1 数据库和 R2 存储数据通常保存在项目根目录下的 .wrangler 文件夹中。如果您希望清空本地测试数据重来，只需删除该文件夹，重新运行本地迁移即可。

身份验证

ShipSaaS 使用什么身份验证系统？

我们内置了 Better Auth 作为身份验证方案。它是一个现代、极速、类型安全且框架无关的 Web 身份验证库，支持传统的邮箱/密码登录，以及各大主流平台的 OAuth 社交登录（GitHub、Google、Microsoft 等）。

订阅与支付

模板支持哪些支付系统？

我们目前原生支持两大支付平台：

1. Stripe：全球最主流的在线信用卡/借记卡支付方案，适合大多数企业和个人开发者。
2. Creem：针对独立开发者和数字资产销售进行了极大优化的现代支付系统。

您可以根据需求配置其中一个或两个，请参阅 支付系统配置 了解详细步骤。

部署与运维

部署到 Cloudflare 后为什么提示找不到环境变量？

Cloudflare Workers 的环境变量需要在 wrangler.jsonc 文件中进行绑定，或者在 Cloudflare Dashboard 的 Worker 设置中添加。

• 在开发环境中，变量从 .dev.env 加载。
• 在生产环境中，Wrangler 会自动读取 wrangler.jsonc 中的配置，请确保在部署前正确同步了敏感密钥。