快速开始
从零开始搭建 01MVP 本地开发环境
前置要求
开始之前，确认你的机器上已经装好了这几样东西。打开终端，逐个检查：
node --version # 需要 v22.x 或更高
pnpm --version # 需要 9.12.3 或更高
git --version # 任意版本即可| 工具 | 最低版本 | 安装方式 |
|---|---|---|
| Node.js | 22.0+ | 官网下载 或 nvm install 22 |
| pnpm | 9.12.3+ | npm install -g pnpm 或 corepack enable pnpm |
| Git | 任意 | macOS 自带；Windows 用 Git for Windows |
| PostgreSQL | 14+ | Neon 免费版（推荐）或本地安装 |
没有 PostgreSQL？ 最快的方式是去 Neon 注册一个免费账号，创建数据库后直接复制 Connection String。不需要本地安装任何东西。
获取代码
git clone https://github.com/makerjackie/01mvp.git
cd 01mvp从 GitHub 仓库 页面点击 Code > Download ZIP，解压后进入项目目录。
然后安装依赖：
pnpm installpnpm install 会自动处理 monorepo 中所有 package 的依赖关系。如果遇到网络问题，可以试试 pnpm install --registry https://registry.npmmirror.com 使用国内镜像。
配置环境变量
cp apps/01mvp-web/.env.example apps/01mvp-web/.env.local然后用编辑器打开 apps/01mvp-web/.env.local，按需填入下面的变量。
这三个变量不填项目跑不起来。
| 变量 | 说明 | 示例值 |
|---|---|---|
DATABASE_URL | PostgreSQL 连接字符串 | postgresql://user:pass@host:5432/db |
BETTER_AUTH_SECRET | 认证签名密钥 | 用 openssl rand -base64 32 生成 |
NEXT_PUBLIC_SITE_URL | 站点地址 | http://localhost:7001 |
DATABASE_URL 格式必须是 postgresql://用户名:密码@主机:端口/数据库名。用 Neon 的话，直接从控制台复制 Connection String。本地 PostgreSQL 要先手动建库：createdb 01mvp。
接入第三方登录需要去各平台申请 OAuth App，获取 Client ID 和 Secret。
| 变量 | 说明 |
|---|---|
GOOGLE_CLIENT_ID | Google OAuth Client ID |
GOOGLE_CLIENT_SECRET | Google OAuth Client Secret |
GITHUB_CLIENT_ID | GitHub OAuth Client ID |
GITHUB_CLIENT_SECRET | GitHub OAuth Client Secret |
WECHAT_WEBSITE_APP_ID | 微信网页应用 AppID |
WECHAT_WEBSITE_APP_SECRET | 微信网页应用 AppSecret |
WECHAT_SERVICE_ACCOUNT_APP_ID | 微信公众号 AppID（用于扫码登录） |
WECHAT_SERVICE_ACCOUNT_APP_SECRET | 微信公众号 AppSecret |
不填则对应的登录方式不会出现。留空不影响项目启动。
01MVP 支持 Stripe 和 Waffo（Pancake）两种支付渠道，按需配置。
Stripe
| 变量 | 说明 |
|---|---|
STRIPE_SECRET_KEY | Stripe 后端密钥（sk_test_... 或 sk_live_...） |
STRIPE_WEBHOOK_SECRET | Stripe Webhook 签名密钥 |
NEXT_PUBLIC_STRIPE_PRICE_PRO_MONTHLY | Pro 月付价格 ID |
NEXT_PUBLIC_STRIPE_PRICE_PRO_YEARLY | Pro 年付价格 ID |
NEXT_PUBLIC_STRIPE_PRICE_LIFETIME | 终身版价格 ID |
Waffo
| 变量 | 说明 |
|---|---|
WAFFO_MERCHANT_ID | Waffo 商户 ID |
WAFFO_PRIVATE_KEY | Waffo 私钥 |
配置 AI 模型后即可使用项目内置的 AI 对话功能。默认使用 DeepSeek。
| 变量 | 说明 | 默认值 |
|---|---|---|
OPENAI_API_KEY | API Key | （必填） |
OPENAI_BASE_URL | API 地址 | https://api.deepseek.com |
OPENAI_MODEL | 模型名 | deepseek-v4-flash |
支持所有 OpenAI 兼容的 API。比如要换成 OpenAI 官方，把 OPENAI_BASE_URL 改成 https://api.openai.com/v1，OPENAI_MODEL 改成 gpt-4o 即可。
S3 文件存储（腾讯云 COS）
| 变量 | 说明 |
|---|---|
S3_ACCESS_KEY_ID | 访问密钥 ID |
S3_SECRET_ACCESS_KEY | 访问密钥 Secret |
S3_REGION | 存储桶区域，如 ap-guangzhou |
NEXT_PUBLIC_BUCKET_NAME | 桶名称 |
NEXT_PUBLIC_S3_ENDPOINT | 接入点地址 |
邮件发送（Zeabur Email）
| 变量 | 说明 |
|---|---|
ZEABUR_EMAIL_API_KEY | Zeabur Email API 密钥 |
EMAIL_FROM | 发件人地址 |
CONTACT_EMAIL | 联系邮箱 |
环境变量与功能对照
不确定哪些变量必须填？看这张表：
| 功能模块 | 依赖的变量 | 不配置的后果 |
|---|---|---|
| 基本运行 | DATABASE_URL, BETTER_AUTH_SECRET, NEXT_PUBLIC_SITE_URL | 项目无法启动 |
| 用户登录注册 | BETTER_AUTH_SECRET + 各平台 OAuth 变量 | 只能用邮箱密码登录 |
| 第三方登录 | 对应平台的 Client ID/Secret | 该登录方式不显示 |
| AI 对话 | OPENAI_API_KEY | AI 功能不可用 |
| 文件上传 | S3_* 变量 | 上传功能不可用 |
| 支付 | Stripe 或 Waffo 变量 | 无法支付 |
| 邮件 | ZEABUR_EMAIL_API_KEY | 反馈表单和通知邮件发不出 |
初始化数据库
pnpm db:generate # 生成 Prisma 客户端（把数据库 schema 变成 TypeScript 类型）
pnpm db:migrate # 创建迁移文件并执行（在数据库中建表）成功后终端会显示 All migrations have been applied。如果看到连接错误，回去检查 DATABASE_URL。
db:generate 做了什么？ 它读取 Prisma schema 定义，在 src/generated/prisma 下生成类型安全的数据库客户端代码。之后代码里用 prisma.user.findMany() 这样的调用就会有完整类型提示。
启动开发服务器
pnpm dev看到 Ready 字样后，浏览器打开 http://localhost:7001。
开发服务器默认跑在 7001 端口，不是通常的 3000。如果 7001 被占用，Next.js 会自动尝试 7002，但最好确保 7001 可用。
开发常用命令
| 命令 | 用途 |
|---|---|
pnpm dev | 启动开发服务器（http://localhost:7001） |
pnpm build | 生产构建（检查是否有编译错误） |
pnpm lint:all | 格式化 + lint 检查（提交前跑一次） |
pnpm db:studio | 打开 Prisma Studio（数据库可视化） |
pnpm db:migrate | 创建并执行数据库迁移 |
pnpm db:generate | 重新生成 Prisma 客户端 |
pnpm smoke | 路由冒烟测试 |
pnpm type-check:packages | 检查所有 package 的类型 |