文档教程Vibe Coding示例工程【免费下载链接】vibe-vibeThe First Systematic Vibe Coding Open-Source Tutorial | From Zero to Full-Stack, Empowering Everyone to Build Products with AI | Live at: www.vibevibe.cn 首个系统化 Vibe Coding 开源教程 | 零基础到全栈实战让人人都能用 AI 开发产品 | 在线地址www.vibevibe.cn项目地址https://gitcode.com/datawhalechina/vibe-vibe点击查看免费下载本篇文章基于 vibe-vibe 开源教程《Vibe Coding 进阶教程》第十二章英文版索引文档及四个子章节整理而成。核心主题是如何把本地开发好的 Next.js 全栈项目通过Serverless无服务器部署平台 托管数据库组合以近乎零成本的方式发布到公网并利用CI/CD 自动化让git push 即上线。读完本文你将掌握部署平台的核心配置参数与踩坑排查方法、主流平台EdgeOne Pages / Vercel / Cloudflare Pages / 阿里云 ESA的选择与操作流程、GitHub Actions 与真实 CI/CD 配置文件的解读能力以及上线后日志运维、灰度发布与成本优化的实战意识。从临时链接到永久在线部署要解决的问题教程第十二章的开篇场景极具代表性小明通过第十章的 Cloudflare Tunnel 给朋友分享了一个个人豆瓣网站的临时链接结果终端一关链接就失效了。他真正需要的是一个任何人、任何时候都能打开的永久在线地址——这就是部署要解决的核问题。部署的本质非常朴素教程在 12.1 部署到 EdgeOne Pages 中说得直白让一台云上的电脑去执行你本地已经执行过的命令。你在本地跑pnpm install装依赖、跑pnpm build构建项目部署平台做的事情一模一样——区别只在于它 7×24 小时在线并且给你一个公网可访问的 URL。而零成本部署的起步方案老师傅推荐的是两件套组合部署平台负责运行你的前端和后端代码提供Serverless无服务器环境。注意Serverless 不是说没有服务器而是你不需要管理服务器——扩缩容、维护全部由平台接管你只管写代码。数据库托管服务负责存储你的数据。主流部署平台一览教程总览index.md与 12.2 部署到类 Vercel 平台 共同给出了各平台的定位画像平台国内访问免费额度亮点适合场景腾讯云 EdgeOne Pages快个人项目够用基于腾讯全球边缘网络连接 GitHub 后自动部署对 Next.js 支持很好国内用户、本教程主推阿里云 ESA 函数和 Pages快有免费档一站式全栈开发平台深度集成 Git 工作流国内用户、阿里云生态用户Vercel较慢需自定义域名100 GB 带宽/月Next.js 官方部署平台开发者体验最佳海外用户、个人项目Cloudflare Pages较快带宽不限全球 CDN 加速免费额度慷慨支持边缘函数静态优先站点可部署 Next.jsNetlify较慢100 GB 带宽/月内置表单处理与认证静态站点、JAMstackRailway一般$5 免费额度/月支持数据库与后端服务全栈应用、需要后端GitHub Pages一般免费最简单的静态网站托管纯前端项目正如 12.2 反复强调的无论选择哪个平台核心工作流永远只有五步Connect GitHub → Select repository → Configure build settings → Add environment variables → Deploy所有平台解决的是同一个问题把 GitHub 仓库里的代码变成别人能访问的网站。底层逻辑一致不同的只是界面、免费额度和网络覆盖。数据库托管用标准 PostgreSQL 保持架构独立性数据库托管负责存储数据老师傅的推荐是Neon——一个专注于 PostgreSQL 本身的云服务。它有三个关键特性标准 PostgreSQL你通过Drizzle ORM用标准连接字符串连接完全不涉及任何厂商捆绑。想换服务商时只需修改DATABASE_URL这就是保持架构的独立性。无服务器架构按需自动扩缩容空闲时自动挂起省成本但这也带来冷启动延迟后文会讲。免费额度充足个人起步阶段几乎零成本。这一点在仓库中有非常扎实的实现证据demos/README.md 明确写着所有 demo 使用 Neon PostgreSQL。免费注册后创建数据库将连接字符串填入.env并要求每个 demo 使用独立的数据库实例避免表名冲突。三个 demo 项目的 drizzle.config.ts 中数据库凭据统一来自环境变量dbCredentials: { url: process.env.DATABASE_URL! }。demos/demo-01-todo/src/db/index.ts 展示了从环境变量到连接建立的核心链路先校验process.env.DATABASE_URL缺失则抛出DATABASE_URL 环境变量未设置再通过neon()创建连接、drizzle()生成 ORM 实例。依赖上使用neondatabase/serverlessdrizzle-orm/neon-http。// demos/demo-01-todo/src/db/index.ts import { neon } from neondatabase/serverless import { drizzle } from drizzle-orm/neon-http if (!process.env.DATABASE_URL) { throw new Error(DATABASE_URL 环境变量未设置) } const sql neon(process.env.DATABASE_URL)这段源码同时印证了部署时的第一类风险代码里对DATABASE_URL是硬性依赖一旦平台上缺少这个环境变量应用根本无法启动——这正是第十二章环境变量失踪坑位的根源。如果你需要更多后端功能Auth 认证、Storage 存储、Realtime 实时订阅可以考虑Supabase。它本质上就是云端的 PostgreSQL 一套后端服务。但老师傅提醒尽量用 Drizzle ORM 直连数据库而不是大量依赖 Supabase 独有的 JS SDK这样才能保持迁移的灵活性。CI/CD 自动化部署变成保存即发布CI/CD持续集成/持续部署听起来高级在当代开发流程里它的本质就是自动化。过去部署一个网站需要手动打包 - 传到服务器 - SSH 登录服务器 - 重启服务。现在变成了三步本地执行git push把代码推送到 GitHub。GitHub 自动通知部署平台嘿有新代码了部署平台收到信号自动拉取最新代码、下载依赖、运行构建、发布上线。你不需要懂复杂的运维命令——保存即发布。教程点出了一个很妙的类比这种代码变更时自动触发操作的理念和开发阶段的Hooks完全一致。本地 Hooks 自动运行测试和格式化云端 CI/CD 自动运行构建和部署共同构成完整的自动化闭环。部署生命周期完整描述如下本地开发写代码 → 推送到 GitHub 自动触发构建 → 构建成功后生成预览链接国内平台通常 3 小时有效期→ 确认无误后合并到主分支正式上线 → 部署记录超过一定数量后旧部署被标记为失效以节省存储空间。从机制上看当你把 GitHub 仓库连接到 EdgeOne Pages 时平台其实在 GitHub 上注册了一个webhook——相当于有事件就通知我的机制教程用淘宝下单后物流系统主动发短信来类比。每次git pushGitHub 主动通知 EdgeOne后者自动拉代码、装依赖、跑构建、发布上线这就是push-to-deploy——最简单形态的 CI/CD。部署配置核心参数逐项解读在开始部署前理解几个核心配置参数是必要的。现代部署平台能自动识别项目但理解参数才能在出问题时知道从哪排查详细界面流程见 12.1构建设置参数含义本教程取值框架预设选择所用框架如 Next.js平台自动填充推荐配置Next.js根目录代码在仓库中的位置默认仓库根目录./若代码在apps/web/等子目录才需修改构建命令平台在云端执行的构建命令pnpm build或npm run build输出目录构建产物存放位置Next.js 通常是.next或out.nextNode 版本平台预装多个 Node 版本如 18、20、22、24本教程使用 24 大版本24EdgeOne 默认 22多数项目可用默认环境变量部署后需要单独配置。国内平台通常支持批量导入——直接把本地.env文件内容粘贴进去平台自动解析成键值对。注意环境变量的修改只对新部署生效不会影响已有部署修改后必须点击重新部署让平台用新值重建12.1 中的 tip 特别强调这一点。EdgeOne Pages 实操流程与部署踩坑教程 12.1 以 EdgeOne Pages 为主线走了一遍完整流程其中三个部署前确认事项值得单列代码已推送到 GitHub——部署平台需要从 GitHub 拉代码代码只在本地则平台无法访问第十一章已完成。本地pnpm build能成功——这是最重要的一步。云端做的事和本地完全相同本地构建失败云端必然失败。记下.env里的环境变量——.env被.gitignore拦在门外不会上传 GitHub数据库密码和 Auth 密钥都需要在平台上手动配置。流程中的两个中国特色环节值得展开连接 GitHub 时的最小权限原则首次授权时可以选择仅选择仓库只授权要部署的那一个仓库遵循第八章安全部分提到的最小权限原则——只给平台恰好够用的权限。后续要部署其他项目再回来追加。加速区域选择与 ICP 备案这是国内平台特有的步骤。若加速区域包含中国大陆则需要ICP 备案即网站页脚常见的京ICP备xxxxxxxx号个人也可申请但审批通常要一到两周。不想等待可选择全球不含中国大陆无需备案即可立即使用绑定自定义域名后国内访问依然流畅详见第十三章域名部分。坑一Node.js 版本不一致第一次构建出现红色Failed查看日志发现 Node 版本过旧。平台默认 Node 版本可能偏老而 Next.js 项目需要更新的版本。解决到平台设置里把 Node.js Version 调整为与本地一致本教程为 24然后重新部署。典型报错error engine node is incompatible with this module坑二环境变量失踪修正版本后构建成功但访问网页全是报错。原因正是第六章学过的.env文件被.gitignore拦住了GitHub 上根本没有数据库密码和 API Key。解决到平台环境变量页面把本地.env内容一条条复制或批量粘贴整份文件填进去。教程给出的个人豆瓣项目变量示例该结构与仓库中 demo-02-todo-auth 的 Better Auth 方案对应DATABASE_URLpostgresql://... # 数据库连接字符串缺失则应用启动即报无法连接数据库 BETTER_AUTH_SECRETxxx # Auth 密钥缺失则用户登录报 500 错误 BETTER_AUTH_URLhttps://your-domain # Auth 回调地址部署后可再更新每个变量都有明确用途DATABASE_URL缺失导致启动失败BETTER_AUTH_SECRET缺失导致登录失败——这正是仓库 src/db/index.ts 中未设置 DATABASE_URL 直接抛错逻辑的上线版复现。常见构建失败排查表12.1 还给出了一张非常实用的排查表错误关键字原因解决方案engine node is incompatibleNode 版本不匹配在设置中调整 Node 版本Cannot find module依赖安装失败检查package.json与锁文件是否已提交到 GitHubDATABASE_URL is not defined环境变量未配置在环境变量页面添加Build failed 无具体信息构建命令错误确保构建命令与本地一致ENOENT: no such file路径错误检查根目录配置排查原则构建日志是最重要的信息来源答案通常就在最后几行。看不懂的错误可以把日志直接丢给 Claude Code 诊断。类 Vercel 平台速览与选择指南VercelNext.js 的亲爹Vercel 是 Next.js 的创造者与官方推荐部署平台原生支持所有 Next.js 特性无需额外配置。两种部署方式方式一Web UI新手推荐登录 vercel.com → Add New → Project → 选择 GitHub 仓库自动识别 Next.js 框架→ 添加环境变量 → Deploy。成功后获得xxx.vercel.app链接。方式二命令行更快# 安装 Vercel CLI npm i -g vercel # 登录会打开浏览器授权 vercel login # 部署首次运行会询问项目配置 vercel deploy # 部署到生产环境 vercel --prodVercel 的独特优势Preview Deployments——每次创建 Pull Request 都会自动生成独立预览链接可与第十一章的 PR 工作流完美配合评审代码与测试功能同步进行Edge Functions——把动态逻辑复制到全球 CDN 节点让请求在离用户最近的节点处理而不是每次都绕回固定服务器。注意*.vercel.app域名在国内访问不稳定解决方案是绑定自定义域名并配合 Cloudflare DNS 代理加速第十三章内容。Cloudflare Pages无限带宽的吸引力最大卖点免费套餐流量不限个人项目完全不用担心带宽成本即使文章突然爆火带来洪峰流量也不会额外计费。快速体验路径使用官方 Next.js 模板启动器点击后自动完成创建仓库 → 连接 Pages → 首次部署全程不到 2 分钟。部署已有项目的步骤与 EdgeOne、Vercel 几乎完全相同。Cloudflare 生态的补充能力WorkersCloudflare 版边缘函数、D1轻量数据库当前 Neon 方案已足够、R2兼容 S3 API 的对象存储。阿里云 ESA Pages国内另一选项如果你已是阿里云用户或项目主要面向国内用户ESA边缘安全加速是与 EdgeOne 定位相似的另一选择。部署流程控制台创建 Pages 项目 → 连接 GitHub → 配置构建与环境变量 → 选择加速区域大陆同样需要 ICP 备案→ 部署。若已在用 OSS、RDS 等阿里云服务选 ESA 的账号与计费体系更统一。如何选择用户主要在国内EdgeOne Pages 或阿里云 ESA国内边缘节点覆盖更好。用户主要在海外Vercel尤其 Next.js 项目体验最佳或 Cloudflare Pages免费额度最慷慨。用户遍布全球Cloudflare Pages 的无限带宽 全球 CDN 最省心绑定自定义域名后国内外均可快速访问。拿不准随便选一个先跑起来。所有平台都是连接 GitHub 配置构建换平台只需在新平台重复一次配置无需改任何代码迁移成本基本为零——这正是第六章强调保持架构独立性的价值代码在 GitHub 上不依赖任何特定平台。自定义流水线GitHub Actions 与真实 CI/CD 配置文件平台内置的push-to-deploy对个人项目已经够用。但当项目复杂到需要在部署前自动跑测试、检查代码风格、检查类型错误时就需要GitHub Actions——GitHub 自带的 CI/CD 工具12.3。GitHub Actions 的菜谱三要素GitHub Actions 通过.github/workflows/目录下的 YAML 文件配置像一份菜谱告诉 GitHub 何时做、分几步、具体做什么触发条件on定义何时运行例如代码推送到main分支或创建 PR 时。运行环境runs-on指定运行系统通常ubuntu-latest。GitHub 会启动一台临时虚拟机执行任务、执行完即销毁保证每次运行都从干净环境开始。执行步骤steps按顺序执行的具体动作——拉代码 → 装依赖pnpm/npm→ 检查代码风格lint→ 构建build→ 跑测试test。任一环节失败比如测试不通过整个流水线停止PR 页面显示红色 ✗提示该 PR 的代码有问题不应合并。分支与部署环境的对应main分支→ 生产环境用户访问的正式版本合并进main即意味着上线。feature/*分支→ 预览环境每个 PR 自动生成的预览链接仅 PR 参与者可见。个人项目这两层通常够了团队需要更多环境如develop分支对应开发环境时部署平台都支持可以让 Claude Code 帮你配置。仓库实战.cnb.yml 多环境 CI/CD 实例12.3 给出的真实案例正是本仓库根目录的 .cnb.yml——vibe-vibe 教程站点自己就运行在这套 CI/CD 上。核心设计极具参考价值分支策略推送到master自动部署生产环境vibe-vibe-production推送到develop部署开发环境创建 PR 自动构建验证该分支现已废弃注释说明改为 feature → master 工作流。部署流程与你的项目同构pnpm install --frozen-lockfile # 安装依赖 pnpm build # 构建站点 npx -y edgeone pages deploy ./docs/.vitepress/dist -n $EDGEONE_PROJECT_NAME --force -t $EDGEONE_API_TOKEN # 部署到 EdgeOne Pages环境变量管理通过imports引入私有配置文件类似 GitHub SecretsAPI Token 不直接写在配置里imports: - https://cnb.cool/nfeyre/secret/-/blob/main/edgeone-pages-env.ymlYAML 锚点复用用docs_deploy_pipeline定义一次部署流程多处用: *docs_deploy_pipeline复用避免重复配置。配合package.json中的build: vitepress build docs与packageManager: pnpm10.21.0可以看到CI 里执行的每一步都是本地开发时已经验证过的命令。这套配置展示了完整的多环境 CI/CD 工作流开发分支自动部署测试环境、主分支自动部署生产、PR 自动验证与合并。个人项目不必如此复杂但项目成长到需要多环境时这是一份可以直接参考的模板。上线后的运维健康检查、日志排查与平台自动优化12.4 运维基础与成本优化 开篇点明上线不是终点而是运维的起点。应用在公网 7×24 小时运行需要有人看着。对独立开发者来说运维就三件事知道应用是否健康——有没有人访问有没有报错能快速定位问题——哪里坏了从什么时候开始的变更时降低风险——先小范围试新功能再全量发布。分析仪表盘与日志部署平台一般提供分析仪表盘展示运行状态各平台入口不同EdgeOne控制台 → 项目 → 数据分析、VercelDashboard → Project → Analytics、CloudflareDashboard → Workers Pages → Analytics。日志是行车记录仪——出事故时回放就知道发生了什么。教程给出了一个真实案例小明从 EdgeOne 部署日志中发现Error: Connection timed out - database not responding到 Neon 控制台一查发现免费档数据库因长时间无活动被挂起了重新激活后网站恢复正常。日志排查三步法先找红色 ERROR → 定位错误发生时间附近的上下文 → 看不懂就把关键信息丢给 Claude Code 分析。各平台日志入口EdgeOne控制台 → 项目 → 部署日志 运行日志、VercelDashboard → Project → Logs可按时间和关键词过滤、CloudflareDashboard → Workers Pages → 实时日志。平台已经替你做的优化自动扩缩容像手机自动亮度调节根据实际流量自动调整资源无需提前预估需要几台服务器。全球 CDN静态资源HTML/CSS/JS/图片自动分发到全球边缘节点用户就近获取。图片优化自动压缩并转换为高效格式WebP/AVIF上传 2MB 的 PNG 用户可能只下载 200KB。HTTPS自动申请并续期 SSL 证书默认安全连接。在传统服务器上这些需要你自己配置 Nginx、Lets Encrypt、CDN 服务……现在平台全部代劳。你可以主动优化的方向用户反映慢时可以让 Claude Code 帮忙分析常见优化方向图片太大首屏加载慢使用next/image组件按设备尺寸自动提供合适大小的图片。API 太慢白屏时间长检查数据库查询是否缺索引、是否存在 N1 查询问题第六章数据库部分讲过。包体过大JS 下载时间长检查是否引入了不必要的库让 Claude Code分析 bundle 大小找出最大的依赖。无缓存相同数据反复请求添加合理的缓存策略让浏览器和 CDN 缓存不常变化的内容。成本优化与灰度发布分阶段决策关于部署决策核心原则是不要在阶段一就担心阶段三的问题过早优化是万恶之源阶段用户规模策略月成本参考MVP 阶段1,000 用户用免费 Serverless 档零成本起步重点是验证产品而非优化成本¥0增长期1,000–10,000 用户免费额度可能不够升级付费套餐评估混合架构成本增长过快才考虑自建约 ¥50–200企业期10,000 用户仅在合规或性能优化需要时才自建服务器视业务而定免费额度陷阱很多平台的免费额度只够测试一旦有真实用户费用可能指数级增长。务必设置账单告警例如超过 ¥70 发邮件提醒、定期查看用量。免费额度是用来体验的不是用来长期跑生产业务的。具体平台的免费额度细节12.4Vercel免费档每个请求最长 10 秒。你写的 API Routes如/api/books部署后会变成 Serverless Functions大多数 API 10 秒绰绰有余但查询大量数据或调用外部 AI API 时可能超时用户会看到白屏和 504 Gateway Timeout。解决优化 API 性能或升级 Pro执行时间提升到 60 秒。Neon免费档算力时长有限长期不活动的数据库会被挂起下次访问需要冷启动首个请求可能慢 1–2 秒——这正是小明网站打不开事件的原因之一。Supabase免费档只允许 2 个项目且闲置 7 天会被暂停多项目并行时免费档很快不够用。AI 模型成本与智能路由如果应用调用 AI APIOpenAI、Claude、GLM 等模型费用可能成为最大开支。两条建议设置日/月消费上限防止代码 Bug如死循环反复调用 API造成天价账单。智能路由简单任务翻译、摘要用便宜的国产模型GLM、DeepSeek复杂推理用 Claude。在代码里加一层判断让请求按任务复杂度分发。教程给出案例某 AI 应用通过智能路由70% GLM 30% Claude将 API 成本降低 80%。关键是把任务复杂度与模型能力匹配——不要用大炮打蚊子。轻量灰度金丝雀发布灰度发布的思想先给 10% 用户推新版本观察几天没问题再扩到 50%、最后全量出问题能及时止损。个人项目不需要复杂灰度系统预览链接 → 测试 → 合并就是最简单的金丝雀流程在功能分支上开发新功能创建 PR平台自动生成预览链接你和朋友在预览链接上测试确认无误后合并 PR 到main自动部署上线这不是严格意义上的金丝雀发布但对个人项目绰绰有余——至少新功能上线前有人测过了。本章学习路径与下一步第十二章的四个子章节构成完整的部署 → 自动化 → 运维主线部署到 EdgeOne Pages → 手把手完成第一次部署拿到公网链接部署到类 Vercel 平台 → 了解更多平台选择找到最适合你的CI/CD 与自动化 → 推送即部署让自动化接管重复劳动运维基础与成本优化 → 上线之后谁来看着它怎么控制成本AI 编程时代的部署告诉 AI 目标平台它会帮你完成配置和部署——但理解上述手动步骤仍然必要因为当自动化出问题时你得知道去哪里排查。上一章是 第十一章Git 版本控制与跨平台协作下一章将进入 第十三章域名、DNS 与 HTTPS把自定义域名绑到应用上让链接看起来更专业——同时也解决预览链接 3 小时有效期的限制。赞分享文档教程Vibe Coding示例工程【免费下载链接】vibe-vibeThe First Systematic Vibe Coding Open-Source Tutorial | From Zero to Full-Stack, Empowering Everyone to Build Products with AI | Live at: www.vibevibe.cn 首个系统化 Vibe Coding 开源教程 | 零基础到全栈实战让人人都能用 AI 开发产品 | 在线地址www.vibevibe.cn项目地址https://gitcode.com/datawhalechina/vibe-vibe点击查看免费下载相关推荐Wails自动化部署终极指南从开发到发布的完整CI/CD流水线Wails自动化部署终极指南从开发到发布的完整CI/CD流水线 想要将Wails桌面应用程序的开发流程提升到专业级别吗本指南将带你全面掌握Wails自动化部桌面应用跨平台CLI前端Nakama分布式服务器完整的CI/CD自动化测试与部署实践指南Nakama分布式服务器完整的CI/CD自动化测试与部署实践指南 Nakama是一个专为社交和实时游戏应用设计的分布式服务器提供完整的后端解决方案。本文将详后端即时通讯社交游戏开发终极指南如何使用Onyx实现从手动部署到一键发布的CI/CD自动化流水线终极指南如何使用Onyx实现从手动部署到一键发布的CI/CD自动化流水线 Onyx是一款开源AI平台支持与各种LLM集成的AI聊天功能。本文将详细介绍如何利AI 应用大模型RAGAI Agent后端前端上一篇深入解读 SeaweedFS 所依赖的 Rust 纠删码库 reed-solomon-erasure从版本演进看其设计演进与性能优化之路下一篇如何快速上手Vitis AI5分钟搭建你的FPGA AI开发环境创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考