Screenshot Studio 部署指南:从本地开发到 Vercel 生产的完整流程
Screenshot Studio 部署指南:从本地开发到 Vercel 生产的完整流程
Screenshot Studio 是一款免费开源的浏览器端截图美化与视觉设计编辑器,支持背景、设备边框、3D 透视、阴影等设计能力,可导出 PNG、JPEG、WebP 乃至 MP4 视频。本文带你从零开始完成 Screenshot Studio 部署:本地开发环境搭建、环境变量配置,直到一键发布到 Vercel 生产环境,全程无需注册账号、无水印。
部署前准备:环境与工具清单 📋
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 做了原生适配,接入非常简单:
- 导入仓库:在 Vercel 控制台 Import 该仓库,框架自动识别为 Next.js,构建命令即
package.json中的npm run build(内部已包含prisma generate)。 - 配置环境变量:在 Project Settings → Environment Variables 填入上表中的变量,至少包含
DATABASE_URL。 - 推送即部署:每次推送到
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 全栈部署的优秀范例。



