Screenshot Studio 部署指南:从本地开发到 Vercel 生产的完整流程

原创2026-10-16 06:36:321,972 阅读

Screenshot Studio 部署指南:从本地开发到 Vercel 生产的完整流程

Screenshot Studio 是一款免费开源的浏览器端截图美化与视觉设计编辑器,支持背景、设备边框、3D 透视、阴影等设计能力,可导出 PNG、JPEG、WebP 乃至 MP4 视频。本文带你从零开始完成 Screenshot Studio 部署:本地开发环境搭建、环境变量配置,直到一键发布到 Vercel 生产环境,全程无需注册账号、无水印。

Screenshot Studio 编辑器界面示例

部署前准备:环境与工具清单 📋

Screenshot Studio 基于 Next.js 16 + React 19 + TypeScript 构建,ARCHITECTURE.md 中有完整的技术栈说明。部署前请确认以下依赖:

依赖项 版本要求 用途
Node.js 20.9 及以上 运行 Next.js 开发/构建
npm 随 Node 自带 安装依赖、执行脚本
PostgreSQL 任意稳定版 存储网站截图缓存(prisma/schema.prisma 中的 ScreenshotCache 表)
Cloudflare R2 可选 对象存储,缓存截图与静态素材

💡 提示:浏览器端编辑器本身不需要数据库即可运行;DATABASE_URL 是 Prisma 在启动和构建阶段的硬性要求,给一个本地占位值就能跑起来。

第一步:克隆仓库并启动本地开发

打开终端,依次执行以下命令(来自 README.md 的 Run locally 章节):

git clone https://gitcode.com/gh_mirrors/sc/screenshot-studio
cd screenshot-studio
npm ci

创建本地 .env 文件,写入一个占位数据库地址即可满足构建要求:

printf 'DATABASE_URL="postgresql://localhost:5432/screenshot_studio"\n' > .env

然后启动开发服务器:

npm run dev

该脚本会先执行 prisma generate 再生成客户端,随后启动 next dev。浏览器打开 http://localhost:3000,进入 /editor 即可体验完整的截图美化编辑器:上传截图、更换背景、加文字与设备边框、导出多格式图片。

截图美化的浏览器边框效果示例

第二步:配置环境变量

生产部署前,建议在 Vercel 控制台或本地 .env 中配置好关键变量(敏感信息切勿提交到仓库,参考 CONTRIBUTING.md 的约定):

变量名 必填 说明
DATABASE_URL ✅ PostgreSQL 连接串,Prisma 与截图缓存必需
R2_ACCOUNT_ID / R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY / R2_BUCKET_NAME 可选 Cloudflare R2 凭据,用于截图缓存与素材代理,见 lib/screenshot-cache.ts
NEXT_PUBLIC_R2_PUBLIC_URL 可选 R2 公开访问域名,配置后 /r2-assets/* 代理生效(next.config.ts 中的 rewrites)
SCREENSHOT_API_URL 可选 网站截图抓取 API 地址,默认使用免密钥的 Microlink 服务
CLEANUP_SECRET 可选 缓存清理接口的访问密钥(app/api/cleanup-cache/route.ts)
INDEXNOW_KEY 可选 IndexNow 索引推送密钥

关于 R2 与数据库的分工:R2 存放截图图片本体,PostgreSQL 记录 URL 哈希与缓存时间,实现"同一网址只抓取一次"的加速缓存。

应用商店截图尺寸与设备样机

第三步:本地验证再上线 🔍

上线前建议在仓库根目录(.env 已配置的状态下)跑一遍完整检查,这是 CONTRIBUTING.md 推荐的验证组合:

npm test          # 回归测试(tests/ 目录)
npm run lint      # ESLint 检查
npx tsc --noEmit  # TypeScript 类型检查
npm run build     # 生产构建(自动先执行 prisma generate)

本地还可用 npm start 启动生产模式的 next start,重点验证以下页面:

  • /editor:核心编辑器,注意该路由带有 COOP/COEP 响应头以启用多线程 FFmpeg WASM 导出
  • /tools:压缩、裁剪、格式转换等图片工具
  • /store-screenshots:应用商店截图批量工作流

第四步:发布到 Vercel 生产环境 🚀

项目对 Vercel 做了原生适配,接入非常简单:

  1. 导入仓库:在 Vercel 控制台 Import 该仓库,框架自动识别为 Next.js,构建命令即 package.json 中的 npm run build(内部已包含 prisma generate)。
  2. 配置环境变量:在 Project Settings → Environment Variables 填入上表中的变量,至少包含 DATABASE_URL。
  3. 推送即部署:每次推送到 main 分支都会自动触发构建与部署,预览环境可先验证再合并。

部署细节有两个值得了解的点:

  • vercel.json 针对截图 API 路由(app/api/screenshot/route.ts)单独配置了函数内存 1024 MB 与 maxDuration,保证长时间外部抓图不会超时;
  • 根目录的 app/api/screenshot/route.ts 中声明了 maxDuration = 60,为外链网站截图抓取预留充足时间,并对每个 IP 做了 20 次/分钟的限流。

生产环境上线后的截图美化效果

常见问题排查 ❓

构建报错缺少 Prisma Client npm run dev / npm run build 均已内置 prisma generate;若手动执行 next build 报错,请先单独运行 npx prisma generate。

编辑器可用但"网站截图"功能不生效 未配置 R2 与数据库时,服务端缓存不可用,抓图仍走 Microlink 直连,速度较慢且无缓存;配置 R2_* 与 DATABASE_URL 后即可获得 2 天有效期的截图缓存。

COEP/COOP 相关报错 这些响应头只加在 /editor、/compress-video、/remove-background 等路由上(见 next.config.ts),请勿自行全局添加,否则首页的嵌入视频会被破坏。

如何升级验证 每次部署后打开 /editor 检查上传、编辑、导出链路,并用 npm test 在本地确认无回归即可。

总结

至此,你已完整掌握 Screenshot Studio 部署流程:克隆仓库 → 配置 .env → 本地验证 → Vercel 一键上线。整个过程中,Next.js 负责全栈渲染,Prisma + PostgreSQL 管理截图缓存,Cloudflare R2 提供低成本对象存储,Vercel 则承担 Serverless 函数与全球分发。按照 README.md 与 CONTRIBUTING.md 的约定继续探索源码,你会发现这个项目是一个学习 Next.js 全栈部署的优秀范例。

登录后查看全文
screenshot-studio