01MVP 实战手册推荐阅读AI 工具教程实战案例Skills 手册模板指南关于
00 / 00

快速开始

从零开始搭建 01MVP 本地开发环境

前置要求

开始之前，先把本地开发会用到的东西备齐。这里先不要求你买域名、配置 Cloudflare 或接支付；那些是上线前的准备。

本地开发必需

node --version      # 需要 v24.x
vp --version        # 需要 Vite Plus CLI
git --version       # 任意版本即可
工具最低版本安装方式
Node.js24.x官网下载 或 nvm install 24
Vite Plus CLI0.1.22+curl -fsSL https://vite.plus | bash 或 npm install -g vite-plus
Git任意macOS 自带；Windows 用 Git for Windows
PostgreSQL14+本机 Homebrew、项目 Docker 开发库，或 Neon / Zeabur 等远程 PostgreSQL

真实上线前再准备

项目什么时候需要用来做什么
自己的域名上线前生产站点、OAuth 回调、支付回调、邮件发信域名和用户信任
Cloudflare 账号上线前DNS、HTTPS、WAF、DDoS 防护、Web Analytics、R2 等基础设施
Zeabur 或其他部署平台账号上线前部署 TanStack Start 服务、生产数据库和后台任务
本地 AI coding agent开发和部署时例如 Codex、Claude Code，用来读代码、改文件、跑命令、排错和操作部署工具
GitHub 或私有 Git 仓库协作和部署前保存代码、触发部署、做版本回滚

AI agent 不参与线上运行。它的作用更像一个会执行命令的本地开发助手：帮你修改代码、检查错误、生成部署配置、根据日志修问题。你也可以手动完成这些事，只是会慢很多。

不想本机安装 PostgreSQL？ 可以去 Neon 或者 Zeabur 创建一个开发数据库，然后直接复制 Connection String。

项目的 packageManager 声明为 [email protected]，日常命令通过 vp install、vp run 和 vp check 执行，Vite Plus 会按声明的包管理器处理安装。

第一次接触 Vite Plus 的话，可以先看 Vite Plus 工具链。那里解释了 vp、vpr、vpx 的区别，以及它们和传统 pnpm、vitest、eslint 命令的对应关系。

获取代码

模板正在小范围内测，完整代码以会员开放后的私有仓库或下载包为准。拿到访问权限后，用下面两种方式之一进入项目。

	git clone <你的 01MVP 模板仓库地址>
	cd 01mvp

从会员页提供的下载入口或私有 GitHub 仓库点击 Code > Download ZIP，解压后进入项目目录。

然后安装依赖：

vp install

vp install 会自动处理 monorepo 中所有 package 的依赖关系。如果遇到网络问题，可以试试 vp install --registry https://registry.npmmirror.com 使用国内镜像。

准备 PostgreSQL

本地开发需要一个 PostgreSQL 数据库。你可以装在本机，也可以用远程开发库；只要最后拿到一个 DATABASE_URL，后面的迁移和启动命令都一样。

macOS 上可以用 Homebrew 安装 PostgreSQL 18：

brew update
brew install postgresql@18

Apple Silicon Mac 的 Homebrew 默认装在 /opt/homebrew。如果你的 Homebrew 在 /usr/local，把下面路径里的 /opt/homebrew 换成 /usr/local。

echo 'export PATH="/opt/homebrew/opt/postgresql@18/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

启动 PostgreSQL 服务并创建开发库：

brew services start postgresql@18

createdb myapp_dev
psql myapp_dev

能进入 psql 就说明数据库已经可用。退出 psql：

\q

Homebrew 初始化的本机 PostgreSQL 会默认使用你的 macOS 当前用户名作为 PostgreSQL 用户。这里不需要单独 createuser，也不需要设置密码，products/01mvp/packages/config/.env 里直接写：

DATABASE_URL="postgresql://localhost:5432/myapp_dev"

如果你不想在本机维护 PostgreSQL，可以用 Neon、Zeabur 或其他 PostgreSQL 服务商创建一个远程开发库。创建完成后复制服务商给出的连接字符串，写入 products/01mvp/packages/config/.env：

DATABASE_URL="postgresql://user:password@host:5432/dbname"

有些服务商要求 SSL，例如 Neon 的连接串通常会带上 ?sslmode=require。复制时保留完整参数。

DATABASE_URL="postgresql://user:password@host:5432/dbname?sslmode=require"

模板也带了一个 Docker 版开发库，适合已经在本机使用 Docker 的场景：

vpr @01mvp/product#db:dev:start

对应的连接字符串：

DATABASE_URL="postgresql://postgres:changeme@localhost:5432/01mvp-start"

如果 5432 端口已经被 Homebrew PostgreSQL 占用，就不要同时启动 Docker 版 PostgreSQL。二选一即可。

配置环境变量

01MVP 本地开发优先使用产品级 env。先复制产品自己的示例文件：

cp products/01mvp/packages/config/.env.example products/01mvp/packages/config/.env

然后用编辑器打开 products/01mvp/packages/config/.env，按需填入下面的变量。products/01mvp/apps/web 的 dev、build、start 脚本都会通过 dotenvx 读取这个文件。

如果多个产品需要共享同一批默认值，可以再复制根目录的 shared env：

cp packages/config/.env.example packages/config/.env

脚本会先读取产品级 .env，再读取 packages/config/.env 作为共享兜底。VITE_WEB_URL、VITE_SERVER_URL、AUTH_COOKIE_PREFIX、EMAIL_FROM 这类同名变量通常放在产品级 env，避免多个产品互相影响。

这四个变量不填项目跑不起来。

变量说明示例值
DATABASE_URLPostgreSQL 连接字符串postgresql://localhost:5432/myapp_dev
BETTER_AUTH_SECRET认证签名密钥用 openssl rand -base64 32 生成
VITE_WEB_URL站点地址http://localhost:7001
VITE_SERVER_URLAPI 地址http://localhost:7001/api

本机 Homebrew PostgreSQL 可以使用 postgresql://localhost:5432/myapp_dev 这种无用户名、无密码的连接串；客户端会默认使用当前 macOS 用户。远程 PostgreSQL 通常需要服务商提供的完整连接串。

接入第三方登录需要去各平台申请 OAuth App，获取 Client ID 和 Secret。

变量说明
GOOGLE_CLIENT_IDGoogle OAuth Client ID
GOOGLE_CLIENT_SECRETGoogle OAuth Client Secret
GITHUB_CLIENT_IDGitHub OAuth Client ID
GITHUB_CLIENT_SECRETGitHub OAuth Client Secret
AUTH_ENABLE_WECHAT是否启用微信登录，默认 false
WECHAT_WEBSITE_APP_ID微信网页应用 AppID
WECHAT_WEBSITE_APP_SECRET微信网页应用 AppSecret
WECHAT_SERVICE_ACCOUNT_APP_ID微信公众号 AppID（用于扫码登录）
WECHAT_SERVICE_ACCOUNT_APP_SECRET微信公众号 AppSecret

OAuth 凭据不填则对应的登录方式不会出现。微信登录还需要设置 AUTH_ENABLE_WECHAT=true。留空不影响项目启动。

当前 TanStack Start 模板已经接入数字商品和 ZPAY 回调；Stripe 等渠道保留为扩展方向，按需配置。

ZPAY

变量说明
ZPAY_PIDZPAY 商户 ID
ZPAY_KEYZPAY 密钥
ZPAY_SUBMIT_URLZPAY 收银台地址
ZPAY_DEFAULT_TYPE默认支付方式，如 alipay

配置 AI 模型后即可使用项目内置的 AI 对话功能。默认使用 DeepSeek。

变量说明默认值
OPENAI_API_KEYAPI Key（必填）
OPENAI_BASE_URLAPI 地址https://api.deepseek.com
OPENAI_MODEL模型名deepseek-v4-flash

支持所有 OpenAI 兼容的 API。比如要换成 OpenAI 官方，把 OPENAI_BASE_URL 改成 https://api.openai.com/v1，OPENAI_MODEL 改成 gpt-4o 即可。

Drop 页面存储（R2 示例）

变量说明
PAGES_BASE_URLDrop 公开页面基础地址
DROP_R2_BUCKET_NAMER2 存储桶名称
DROP_R2_ACCOUNT_IDCloudflare Account ID
DROP_R2_ENDPOINTR2 S3 兼容 API 地址
DROP_R2_ACCESS_KEY_ID访问密钥 ID
DROP_R2_SECRET_ACCESS_KEY访问密钥 Secret
DROP_R2_REGION存储桶区域，R2 填 auto

R2 场景里，DROP_R2_ENDPOINT 指向 r2.cloudflarestorage.com，给服务端上传和读取 Drop 页面使用。密钥只放在 DROP_R2_ACCESS_KEY_ID / DROP_R2_SECRET_ACCESS_KEY，不要暴露给前端。

邮件发送（Zeabur Email）

变量说明
ZEABUR_EMAIL_API_KEYZeabur Email API 密钥
EMAIL_FROM发件人地址
FEEDBACK_EMAIL_TO反馈收件邮箱

环境变量与功能对照

不确定哪些变量必须填？看这张表：

功能模块依赖的变量不配置的后果
基本运行DATABASE_URL, BETTER_AUTH_SECRET, VITE_WEB_URL, VITE_SERVER_URL项目无法启动
用户登录注册BETTER_AUTH_SECRET + 各平台 OAuth 变量只能用邮箱密码登录
多产品 Cookie 隔离AUTH_COOKIE_PREFIX，需要 SSO 时再设置 COOKIE_DOMAIN默认使用 01MVP 产品前缀和 host-only Cookie
第三方登录对应平台的 Client ID/Secret该登录方式不显示
AI 对话OPENAI_API_KEYAI 功能不可用
Drop 页面发布DROP_R2_* 变量生产环境无法写入 R2；本地开发会回退到本地目录
支付ZPAY 变量无法创建生产支付链接
邮件ZEABUR_EMAIL_API_KEY, EMAIL_FROM反馈表单邮件发不出

初始化数据库

下面命令默认从仓库根目录运行，使用 Vite Plus 的 vpr <package>#<script> 短写：

vpr @01mvp/product#db:generate   # 根据 Drizzle schema 生成迁移文件
vpr @01mvp/product#db:migrate    # 执行迁移文件（在数据库中建表）

成功后终端会显示 All migrations have been applied。如果看到连接错误，回去检查 DATABASE_URL。

db:generate 做了什么？ 它读取 products/01mvp/packages/db/src/schema 下的 Drizzle schema，并在 products/01mvp/packages/db/migrations 下生成 SQL migration 文件。之后用 vpr @01mvp/product#db:migrate 把这些迁移执行到数据库。

创建本地测试管理员

本地开发和浏览器自动化验收经常需要一个固定管理员账号。迁移完成后可以运行：

vpr @01mvp/product#db:seed

默认账号：

email: [email protected]
password: Admin123456

这个命令会创建或更新一个 super_admin 用户，并为它写入 Better Auth 的邮箱密码登录凭据。默认只允许写入本地数据库；如果 DATABASE_URL 指向远程地址，命令会拒绝执行。

如果你明确使用的是可丢弃的远程开发库，可以手动放行：

vpr @01mvp/product#db:seed -- --allow-remote

不要对生产数据库运行 db:seed。生产环境的管理员账号应通过正式注册、后台授权或平台 Secret 管理。

启动开发服务器

vpr @01mvp/product#dev

看到 Ready 字样后，浏览器打开 http://localhost:7001。

开发服务器默认跑在 7001 端口，不是通常的 3000。如果 7001 被占用，TanStack Start 会自动尝试 7002，但最好确保 7001 可用。

开发常用命令

Vite Plus 支持两种日常写法：进入产品目录后运行产品脚本，或者在仓库根目录指定 package。根目录最推荐用 vpr <package>#<script> 短写；需要给 CI 或文档写完整命令时，用 vp run --filter <package> <script>。完整说明见 Vite Plus 工具链。

操作进入 products/01mvp 后仓库根目录
启动开发服务器vpr devvpr @01mvp/product#dev
生产构建vpr buildvpr @01mvp/product#build
Lint 检查vpr lintvpr @01mvp/product#lint
类型检查vpr type-checkvpr @01mvp/product#type-check
运行测试vpr testvpr @01mvp/product#test
打开 Drizzle Studiovpr db:studiovpr @01mvp/product#db:studio
执行迁移vpr db:migratevpr @01mvp/product#db:migrate
生成迁移vpr db:generatevpr @01mvp/product#db:generate
准备本地管理员vpr db:seedvpr @01mvp/product#db:seed
检查文档链接vpr docs:check-linksvpr @01mvp/product#docs:check-links

只跑某个 app 或 package 时，直接指定对应 package：

vpr @01mvp/web#dev
vpr @01mvp/web#test
vpr @01mvp/web#type-check
vpr @01mvp/web#build
vpr @01mvp/i18n#build

全仓格式化仍然在根目录运行：

vp check --fix

常见问题

下一步

项目架构

理解 monorepo 结构，知道代码该放哪里。

UI 与主题

了解主题预设系统和组件架构。

开发规范

代码风格、Git 提交规范和开发流程。

数据库操作

用 Drizzle 管理 schema、迁移和查询。

这篇文档有问题？

On this page

前置要求本地开发必需真实上线前再准备获取代码准备 PostgreSQL配置环境变量环境变量与功能对照初始化数据库创建本地测试管理员启动开发服务器开发常用命令常见问题下一步