快速开始
校验交付的源码归档包，配置 Starter 并在本地运行。
VibeAny 以源码归档包交付，你可以据此定制自己的 SaaS。本指南将沿受支持的设置流程，带你从校验交付文件到启动可用的本地应用。
前置条件
开始前请安装：
- Node.js 24.0.1 或更高版本
- npm 11.3.0 或更高版本
- 如果要使用随附的本地 PostgreSQL 和 Mailpit 服务，请安装 Docker Desktop 或其他兼容 Docker 的运行时
- 如果使用托管数据库，请准备一个标准的 PostgreSQL 连接 URL
Starter 使用 package-lock.json 锁定依赖，并且只支持 npm。
1. 验证并解压归档包
请将源码归档包和对应的 .sha256 校验文件放在一起。解压前先验证传输校验和：
shasum -a 256 -c vibeany-starter-<version>.tar.gz.sha256
tar -xzf vibeany-starter-<version>.tar.gz
cd vibeany-starter-<version>解压后的根目录还包含 release-manifest.json 和 SHA256SUMS。这个校验文件用于验证压缩归档包，SHA256SUMS 则描述本次交付的源码清单。
不要将解压后的 Starter 源码发布到公开仓库。你的订单和随附的商业许可证决定了哪些人可以访问和使用源码。
2. 安装精确版本的依赖
npm ci使用 npm ci 根据随附的锁文件进行干净、可复现的安装。首次设置时，不要替换锁文件或切换包管理器。
3. 运行设置向导
npm run setup向导会引导你完成受支持的本地设置：
- 选择随附的 Docker PostgreSQL 服务，或提供外部 PostgreSQL URL。
- 继续之前测试数据库连接。
- 如果尚未配置，生成
BETTER_AUTH_SECRET。 - 启用邮箱和密码身份认证。
- 按需配置 Google OAuth。
- 按需配置一个支付服务商：Stripe 或 Creem。
- 写入或更新
.env.local，但不提交该文件。 - 按需执行已提交的数据库迁移。
选择 Docker 数据库时，向导会同时启动 PostgreSQL 和 Mailpit。如果使用外部数据库但仍希望在本地捕获邮件，请单独启动 Mailpit：
docker compose up -d mailpit以后可以再次运行向导来添加可选集成。当向导询问保留还是替换现有值时，请先检查当前配置。
4. 启动应用
npm run dev打开 http://localhost:3000。根路由会重定向到默认语言，目前是 /en。
5. 验证本地基线
使用以下路由检查核心应用：
| 路由 | 预期结果 |
|---|---|
/en | 本地化的营销首页正常加载。 |
/en/signup | 启用邮箱身份认证后，可以使用邮箱注册。 |
/en/login | 登录页显示所有已配置的登录方式。 |
/en/dashboard | 匿名请求会重定向到 /en/login，并携带返回路径。 |
/en/pricing | 定价页正常加载；配置支付前，购买控件保持禁用。 |
测试本地邮箱身份认证时，注册后打开 http://localhost:8025。Mailpit 会捕获验证邮件和密码重置邮件，不会将它们发送到公网。
手动设置
如果不想使用向导，可以复制文档中的环境变量模板并启动本地服务：
cp .env.example .env.local
docker compose up -d db mailpit
openssl rand -base64 32将生成的密钥和本地配置写入 .env.local：
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/vibeany
BETTER_AUTH_SECRET=<generated-secret>
NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_ENABLE_EMAIL_AUTH=true
NEXT_PUBLIC_ENABLE_PAYMENTS=false执行已提交的迁移，然后启动 Next.js：
npm run db:migrate
npm run dev绝不要使用 db:push 或 drizzle-kit push。VibeAny 明确要求所有环境都只能使用经过审查并已提交的迁移。
如果 5432 端口已被占用，可以让向导配置其他主机端口：
VIBEANY_POSTGRES_PORT=55432 npm run setup使用结束后停止随附的服务：
docker compose down