1. 为什么选择 Cloudflare Pages D1 组合最近在折腾个人影视库项目时我发现了 MoonTV 这个宝藏开源项目。它基于 Next.js 14 构建功能强大但部署成本却可以做到零——这要归功于 Cloudflare 提供的 Pages 和 D1 两大免费服务。作为一个长期自建服务的开发者我实测这套方案确实香特别适合想拥有私人影视库但又不想花钱租服务器的朋友。Cloudflare Pages 本质上是一个静态网站托管服务但它通过 Edge Functions 实现了动态能力。而 D1 则是 Cloudflare 推出的轻量级 SQLite 数据库服务。两者配合使用就能免费搭建一个功能完整的全栈应用。我对比过 Vercel Supabase 的方案虽然也不错但 Cloudflare 这套组合在访问速度和全球分布上更有优势特别是对国内用户而言通过自定义域名可以解决访问问题。2. 前期准备Fork 与配置项目2.1 获取 MoonTV 源码第一步需要把 MoonTV 的代码变成你自己的。打开 GitHub 访问 MoonTV 官方仓库点击右上角的 Fork 按钮。这个过程相当于把项目完整复制到你的账号下之后所有修改都在你自己的副本上进行。这里有个实用技巧Fork 后建议立即开启仓库的 Actions 权限。进入你 Fork 后的仓库 Settings → Actions → General确保 Allow all actions 被选中。这样后续才能自动同步原作者的更新。2.2 关键文件检查Fork 完成后需要确认几个关键文件package.json确认项目依赖和脚本命令vercel.json包含输出目录配置.env.example环境变量模板d1/schema.sql数据库初始化脚本我建议先本地运行试试效果。执行pnpm install pnpm run dev就能启动开发服务器。如果遇到依赖问题可以删除node_modules和pnpm-lock.yaml后重新安装。3. 部署到 Cloudflare Pages3.1 创建 Pages 项目登录 Cloudflare 控制台进入 Pages 服务点击 Create project。选择你 Fork 的 GitHub 仓库作为源这里要注意授权范围选择 All repositories 以免后续权限不足。关键配置项构建命令pnpm install --frozen-lockfile pnpm run pages:build构建输出目录.vercel/output/static框架预设选择 None第一次部署可能会失败这是正常现象。部署完成后需要进入项目设置做两件事在 Functions 选项卡开启nodejs_compat兼容标志在环境变量中添加PASSWORD值随意但不要留空3.2 解决常见部署问题根据我的踩坑经验这里有几个常见问题如果报错 Failed to install dependencies可能是因为 pnpm 缓存问题。可以尝试在构建命令前加上pnpm config set store-dir .pnpm-store页面能打开但接口报错检查是否漏掉了nodejs_compat设置播放器加载失败可能是 HLS.js 的 CSP 限制需要在_headers文件添加Content-Security-Policy规则4. 配置 D1 数据库实现数据持久化4.1 初始化数据库进入 Cloudflare 控制台的 D1 页面点击 Create database。创建完成后我们需要执行初始化脚本-- 在 D1 的 SQL 编辑器中运行 CREATE TABLE IF NOT EXISTS users ( id TEXT PRIMARY KEY, username TEXT UNIQUE, password TEXT, createdAt INTEGER DEFAULT (unixepoch()) ); -- 其他表结构见项目中的 d1/schema.sql更简单的方法是直接导入项目提供的完整 SQL 文件。点击 D1 的 Import 按钮上传d1/schema.sql文件即可。4.2 配置环境变量回到 Pages 的项目设置添加以下环境变量NEXT_PUBLIC_STORAGE_TYPE d1DB_URL值会自动注入无需手动设置USERNAME和PASSWORD用于管理员登录特别注意环境变量名称区分大小写必须完全匹配。部署成功后访问/admin就能看到用户管理界面了。5. 优化访问体验5.1 设置自定义域名Cloudflare 提供的 pages.dev 域名在国内访问不稳定。建议绑定自己的域名在域名注册商处将 DNS 服务器改为 Cloudflare 的在 Cloudflare 控制台添加域名进入 Pages 项目的自定义域名设置完成绑定实测下来使用国内注册的域名 Cloudflare CDN播放体验会稳定很多。5.2 开启 PWA 功能MoonTV 原生支持 PWA渐进式 Web 应用。要让这个功能正常工作需要在next.config.js中确认以下配置const withPWA require(next-pwa)({ dest: public, disable: process.env.NODE_ENV development }); module.exports withPWA({ // 其他配置... });部署后浏览器访问时会自动提示添加到主屏幕这样就能获得类似原生应用的体验了。6. 日常维护与更新6.1 同步上游更新MoonTV 原作者会持续更新项目。要获取这些更新有两种方式手动同步在你 Fork 的仓库页面点击 Sync fork 按钮自动同步编辑.github/workflows/sync.yml文件取消注释定时任务部分我推荐设置自动同步这样每周都会自动拉取最新代码。同步后 Pages 会自动触发重新部署完全无需人工干预。6.2 自定义配置项目根目录的config.json文件支持多种自定义修改sites数组可以增减搜索源proxy设置可以改善某些源的播放成功率announcement添加站点公告更改这些配置后推送到 GitHub 就会自动触发重新部署。建议每次修改前先备份原文件避免配置错误导致服务中断。这套方案我已经稳定运行了三个月播放记录和收藏在多设备间同步完美最重要的是完全免费。如果你在部署过程中遇到问题可以尝试删除项目重新部署有时候环境缓存会导致一些奇怪的问题。对于影视爱好者来说这可能是目前性价比最高的自建方案了。
基于 Cloudflare Pages + D1 构建 MoonTV 影视库：从零到一的免费全栈部署实践
发布时间：2026/7/5 8:07:47
1. 为什么选择 Cloudflare Pages D1 组合最近在折腾个人影视库项目时我发现了 MoonTV 这个宝藏开源项目。它基于 Next.js 14 构建功能强大但部署成本却可以做到零——这要归功于 Cloudflare 提供的 Pages 和 D1 两大免费服务。作为一个长期自建服务的开发者我实测这套方案确实香特别适合想拥有私人影视库但又不想花钱租服务器的朋友。Cloudflare Pages 本质上是一个静态网站托管服务但它通过 Edge Functions 实现了动态能力。而 D1 则是 Cloudflare 推出的轻量级 SQLite 数据库服务。两者配合使用就能免费搭建一个功能完整的全栈应用。我对比过 Vercel Supabase 的方案虽然也不错但 Cloudflare 这套组合在访问速度和全球分布上更有优势特别是对国内用户而言通过自定义域名可以解决访问问题。2. 前期准备Fork 与配置项目2.1 获取 MoonTV 源码第一步需要把 MoonTV 的代码变成你自己的。打开 GitHub 访问 MoonTV 官方仓库点击右上角的 Fork 按钮。这个过程相当于把项目完整复制到你的账号下之后所有修改都在你自己的副本上进行。这里有个实用技巧Fork 后建议立即开启仓库的 Actions 权限。进入你 Fork 后的仓库 Settings → Actions → General确保 Allow all actions 被选中。这样后续才能自动同步原作者的更新。2.2 关键文件检查Fork 完成后需要确认几个关键文件package.json确认项目依赖和脚本命令vercel.json包含输出目录配置.env.example环境变量模板d1/schema.sql数据库初始化脚本我建议先本地运行试试效果。执行pnpm install pnpm run dev就能启动开发服务器。如果遇到依赖问题可以删除node_modules和pnpm-lock.yaml后重新安装。3. 部署到 Cloudflare Pages3.1 创建 Pages 项目登录 Cloudflare 控制台进入 Pages 服务点击 Create project。选择你 Fork 的 GitHub 仓库作为源这里要注意授权范围选择 All repositories 以免后续权限不足。关键配置项构建命令pnpm install --frozen-lockfile pnpm run pages:build构建输出目录.vercel/output/static框架预设选择 None第一次部署可能会失败这是正常现象。部署完成后需要进入项目设置做两件事在 Functions 选项卡开启nodejs_compat兼容标志在环境变量中添加PASSWORD值随意但不要留空3.2 解决常见部署问题根据我的踩坑经验这里有几个常见问题如果报错 Failed to install dependencies可能是因为 pnpm 缓存问题。可以尝试在构建命令前加上pnpm config set store-dir .pnpm-store页面能打开但接口报错检查是否漏掉了nodejs_compat设置播放器加载失败可能是 HLS.js 的 CSP 限制需要在_headers文件添加Content-Security-Policy规则4. 配置 D1 数据库实现数据持久化4.1 初始化数据库进入 Cloudflare 控制台的 D1 页面点击 Create database。创建完成后我们需要执行初始化脚本-- 在 D1 的 SQL 编辑器中运行 CREATE TABLE IF NOT EXISTS users ( id TEXT PRIMARY KEY, username TEXT UNIQUE, password TEXT, createdAt INTEGER DEFAULT (unixepoch()) ); -- 其他表结构见项目中的 d1/schema.sql更简单的方法是直接导入项目提供的完整 SQL 文件。点击 D1 的 Import 按钮上传d1/schema.sql文件即可。4.2 配置环境变量回到 Pages 的项目设置添加以下环境变量NEXT_PUBLIC_STORAGE_TYPE d1DB_URL值会自动注入无需手动设置USERNAME和PASSWORD用于管理员登录特别注意环境变量名称区分大小写必须完全匹配。部署成功后访问/admin就能看到用户管理界面了。5. 优化访问体验5.1 设置自定义域名Cloudflare 提供的 pages.dev 域名在国内访问不稳定。建议绑定自己的域名在域名注册商处将 DNS 服务器改为 Cloudflare 的在 Cloudflare 控制台添加域名进入 Pages 项目的自定义域名设置完成绑定实测下来使用国内注册的域名 Cloudflare CDN播放体验会稳定很多。5.2 开启 PWA 功能MoonTV 原生支持 PWA渐进式 Web 应用。要让这个功能正常工作需要在next.config.js中确认以下配置const withPWA require(next-pwa)({ dest: public, disable: process.env.NODE_ENV development }); module.exports withPWA({ // 其他配置... });部署后浏览器访问时会自动提示添加到主屏幕这样就能获得类似原生应用的体验了。6. 日常维护与更新6.1 同步上游更新MoonTV 原作者会持续更新项目。要获取这些更新有两种方式手动同步在你 Fork 的仓库页面点击 Sync fork 按钮自动同步编辑.github/workflows/sync.yml文件取消注释定时任务部分我推荐设置自动同步这样每周都会自动拉取最新代码。同步后 Pages 会自动触发重新部署完全无需人工干预。6.2 自定义配置项目根目录的config.json文件支持多种自定义修改sites数组可以增减搜索源proxy设置可以改善某些源的播放成功率announcement添加站点公告更改这些配置后推送到 GitHub 就会自动触发重新部署。建议每次修改前先备份原文件避免配置错误导致服务中断。这套方案我已经稳定运行了三个月播放记录和收藏在多设备间同步完美最重要的是完全免费。如果你在部署过程中遇到问题可以尝试删除项目重新部署有时候环境缓存会导致一些奇怪的问题。对于影视爱好者来说这可能是目前性价比最高的自建方案了。
