Spell UI 部署完整指南：5 步从本地 pnpm dev 到 Vercel 上线

【免费下载链接】spell-uiA large collection of high-quality React components that you can copy and paste into any project.项目地址https://gitcode.com/gh_mirrors/sp/spell-ui点击查看免费下载本指南带你完成 Spell UI 的完整部署流程从本地pnpm dev快速启动到 Vercel 一键上线。Spell UI 是一个基于 Next.js 16 React 19 Tailwind CSS 4 构建的高品质 React 组件库站点跟着走即可零踩坑上线无需任何服务器运维经验。部署前 30 秒了解 Spell UI 的技术栈在开始之前先弄清项目跑在什么技术之上心里就有底了 技术版本作用Next.js16App Router应用框架Vercel 官方深度适配React19组件运行时Tailwind CSS4样式系统pnpm10.5.2包管理器packageManager字段已锁定MDX Content Collections—组件文档与博客渲染Better Auth Drizzle ORM Turso—登录与订阅数据可选功能核心脚本都定义在 package.json 中部署全程只需要记住这四个pnpm dev # 本地开发服务器 pnpm build # 生产构建 pnpm start # 本地预览生产构建 pnpm drizzle:migrate # 应用数据库迁移提示packageManager字段锁定了 pnpm 版本建议本机安装 pnpm 10.x避免版本漂移导致依赖安装异常。第 1 步克隆仓库本地 pnpm dev 三步启动打开终端依次执行以下命令# 克隆仓库 git clone https://gitcode.com/gh_mirrors/sp/spell-ui # 进入目录并安装依赖 cd spell-ui pnpm install # 启动开发服务器 pnpm dev启动成功后浏览器访问http://localhost:3000即可看到 Spell UI 的文档首页和全部组件 Demo。本地需要配环境变量吗浏览文档和组件演示不需要任何环境变量pnpm dev直接可跑。只有当你想体验登录GitHub OAuth或赞助订阅功能时才需要创建一个.env文件该文件已被 .gitignore 中的.env*规则排除不会进仓库# .env本地开发用不会被提交 TURSO_DATABASE_URLlibsql://your-db.turso.io TURSO_AUTH_TOKENyour-token BETTER_AUTH_SECRETyour-random-secret GITHUB_CLIENT_IDyour-github-client-id GITHUB_CLIENT_SECRETyour-github-client-secret其中TURSO_DATABASE_URL/TURSO_AUTH_TOKEN用于连接 Turso 数据库定义在 db/index.tsBETTER_AUTH_SECRET是认证加密密钥代码会回退读取AUTH_SECRET见 lib/auth.tsGitHub 两个变量用于 OAuth 登录定义在 lib/auth.ts第 2 步上线前用 pnpm build 验证生产构建部署前先在本地完整跑一遍生产构建提前暴露问题pnpm build pnpm startpnpm start启动后访问http://localhost:3000这就是线上将运行的样子。构建通过、页面正常说明可以进入部署环节 ✅第 3 步把环境变量一次性配到 VercelVercel 部署的精髓是环境变量不进仓库、在平台侧配置。登录 Vercel进入项目的Settings → Environment Variables按部署阶段Production / Preview / Development添加变量名是否必须说明TURSO_DATABASE_URL用登录/订阅功能时必填Turso 数据库连接地址TURSO_AUTH_TOKEN同上数据库访问令牌BETTER_AUTH_SECRET同上认证密钥可用openssl rand -hex 32生成GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET可选GitHub 登录凭据NEXT_PUBLIC_APP_URL可选站点对外地址app/sitemap.ts、app/robots.ts 和 RSS 会读取它缺省回退到内置地址WHOP_PLAN_ID_*可选赞助订阅套餐 ID见 app/api/whop/webhook/route.ts两个容易踩的坑NEXT_PUBLIC_前缀的变量会暴露到浏览器其余变量只存在于服务端。密钥类变量千万不要加这个前缀。Vercel 内置变量不用手动配。项目通过 lib/get-base-url.ts 自动读取NEXT_PUBLIC_VERCEL_ENV、NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL等变量生成站点地址本地回退到http://localhost:3000零配置即可工作。第 4 步仓库连接 Vercel一键部署将代码推送到远端 Git 仓库在 Vercel 控制台Import Project选择该仓库Vercel 会自动识别 Next.js 框架默认配置构建命令next build即可无需修改点击Deploy等待构建完成部署完成后你会得到Production URL指向main分支的生产地址Preview URL每个分支 / Pull Request 都会自动获得一个独立预览地址方便演示和验收如果修改过组件注册表registry.json 或registry/spell-ui/下的文件构建前记得先执行pnpm registry:build重新生成 public/r/ 中的安装 JSON否则 CLI 拉取的仍是旧组件包。另外项目内置了 CI 迁移工作流 .github/workflows/migrate.ymlmain分支推送后会自动执行pnpm drizzle:migrate同步数据库表结构前提是已在仓库 Secrets 中配置TURSO_DATABASE_URL和TURSO_AUTH_TOKEN。第 5 步上线后验证与常见问题排查✅验证清单访问生产 URL首页、组件文档如/docs/spinner、博客列表均正常访问/sitemap.xml和/robots.txt确认站点地址正确对应NEXT_PUBLIC_APP_URL配置查看构建日志中是否有Failed to compile或环境变量缺失警告❓常见问题现象原因与解法线上 404 或登录跳转错误未配置NEXT_PUBLIC_APP_URL导致回调地址回退到默认域名本地正常、线上数据库连接失败环境变量漏配或写错大小写Vercel 中变量名必须与代码完全一致pnpm install报引擎错误未用 pnpm或版本与packageManager声明的 10.5.2 差距过大构建时 MDX 报错检查 next.config.ts 的 rewrites 与 content-collections.ts 是否被误改 隐藏彩蛋部署成功后的小惊喜恭喜完成部署最后分享一个项目里的小彩蛋在任意页面打开浏览器控制台F12你会看到一只可爱的猫咪。它来自 public/cat.png由 app/layout.tsx 中的easter-egg脚本加载并渲染到控制台——下次给别人演示你的 Spell UI 站点时别忘了秀一下 总结Spell UI 部署全流程一图流git clone→pnpm install→pnpm dev本地 3 分钟跑起来可选本地创建.env配置数据库与认证pnpm build pnpm start验证生产构建环境变量配置到 Vercel 仪表盘仓库连接 Vercel 一键部署验证生产地址、sitemap 与预览部署完成上线 关键文件速查构建脚本与依赖package.json框架与 MDX 配置next.config.ts站点地址解析lib/get-base-url.ts数据库连接db/index.ts认证配置lib/auth.ts贡献者上手流程CONTRIBUTING.md赞分享【免费下载链接】spell-uiA large collection of high-quality React components that you can copy and paste into any project.项目地址https://gitcode.com/gh_mirrors/sp/spell-ui点击查看免费下载相关推荐html-anything部署指南从本地dev到局域网访问、Vercel一键部署的完整教程html anything部署指南从本地dev到局域网访问、Vercel一键部署的完整教程 html anything 是一款 AI Agent 驱动的 HTAI 应用人工智能AI AgentAI 写作媒体生成RedwoodJS 部署到 Vercel 完整指南从零配置到 Serverless 上线RedwoodJS 部署到 Vercel 完整指南从零配置到 Serverless 上线 本篇技术指南基于 Redwood 官方部署文档完整讲解如何将 Re后端前端Web框架开发工具在 Vercel 上构建 Hexo 博客从 Hello World 到本地开发与线上部署的完整指南在 Vercel 上构建 Hexo 博客从 Hello World 到本地开发与线上部署的完整指南 本篇指南以 Vercel 开源仓库中的 Hexo 示例工程CLI后端云原生创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考