写在前面

按照作者提供的Cloudflare部署文档在Windows执行到pnpm cf:deploy 会先后遇到一些问题：

• OpenNext 在 Windows 上确实有兼容性问题 导致打包部署失败；
• Windows 符号链接权限问题 导致打包部署失败；
• 解决完后执行打包部署成功后，访问线上地址，页面展示Internal Server Error 或者500 错误

先说原因：

官方教程就没考虑Windows这个系统，直接在本地执行pnpm cf:deploy就不行。

已知情况：

在Mac上本地执行pnpm cf:deploy成功部署Cloudflare；

在Windows上就是不行，除非用wsl、wrangler技术，但是操作成本有点高，还有失败率，考虑到后期解答时间成本高，此法不可取；

最终解决办法

参考Vercel创建项目部署法思路，因为Cloudflare、Vercel都是基于Linux（环境一致性：避免了 Windows 下文件路径（File Paths）或符号链接（Symlinks）导致的构建产物异常），那么咱们抛弃官方 pnpm cf:deploy方案。

前提：你的项目已经提交到github

而且，你已经在前面的教程做完了db数据库初始化、rbac、admin用户注册分配为super_admin

注意：！！！不要执行下面的命令！！！

cp wrangler.toml.example wrangler.toml

咱们修改根目录下wrangler.jsonc（如果没有就新建wrangler.jsonc，复制下面内容自行修改）

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"main": ".open-next/worker.js",
	"name": "shipany-template-mdx-blog, // 这里和你项目仓库名保持一致
	"compatibility_date": "2025-12-02",
	"compatibility_flags": ["nodejs_compat"],
	"assets": {
		"directory": ".open-next/assets",
		"binding": "ASSETS"
	},
	"r2_buckets": [
		// Use R2 incremental cache
		// See https://opennext.js.org/cloudflare/caching
		{
			"binding": "NEXT_INC_CACHE_R2_BUCKET",
			// Create the bucket before deploying
			// You can change the bucket name if you want
			// See https://developers.cloudflare.com/workers/wrangler/commands/#r2-bucket-create
			"bucket_name": "cache"
		}
	],
	//  ！！！这里是开启日志的配置 ！！！【可删除这条注释】
	"observability": {
		"enabled": true,
		"head_sampling_rate": 1,
		"logs": {
			"enabled": true,
			"head_sampling_rate": 1,
			"invocation_logs": true
		}
	},
    //  ！！！这里是环境变量的配置 ！！！注意：这个会提交到git上，一定要私有仓库，避免泄露，部分值做了xxx处理【可删除这条注释】
	"vars": {
		"NEXT_PUBLIC_APP_URL": "https://xxxx.xxxx.xyz", 
		"NEXT_PUBLIC_APP_NAME":  "Mdx Blog Template",
		"NEXT_PUBLIC_THEME": "default",
		"NEXT_PUBLIC_APPEARANCE": "dark",
		"DATABASE_URL": "postgres://postgres.bobhcicyxxxxsdbvpf:xxxx@aws-1-us-west-1.pooler.supabase.com:5432/postgres",
		"DATABASE_PROVIDER": "postgresql",
		"DB_SINGLETON_ENABLED": "false",
		"DB_MAX_CONNECTIONS": "10",
		"AUTH_SECRET": "wGxL6wMsyxxxxDC0lfRzgl3PzHPMZDAN+s="
	}
}

访问Cloudflare › Workers & Pages，创建

// pnpm cf:build

成功后按照上面截图提供的地址访问看看能否正常访问

如果你要部署非main分支的代码到Cloudflare上请阅读下面这段教程，否则直接略过直接往下看

到Cloudflare-Workers & Pages-当前项目的Settings


然后本地代码再提交一次github触发自动部署

后续怎么触发Cloudflare自动部署呢？

你直接提交（Push）对应分支代码的变动到仓库就会自动触发 Cloudflare 的自动部署。你不需要做额外操作

git提交后，怎么查看部署过程和记录呢？

看下图，点击后再返回就能看到所有的build 记录：

绑定自定义域名

如果你没有域名, 请阅读：如何购买便宜的域名

第一种：在 Cloudflare 添加自定义域名

如果你的域名是在其他域名服务商（Godaddy、Namecheap 等）注册的，你可以选择在 Cloudflare 添加自定义域名。

这一种主要存在新域名第一次在Cloudflare上配置。

然后去你的域名管理后台，把域名的 NAMESERVER 设置为 Cloudflare 提供的 Nameservers

graham.ns.cloudflare.com
ullis.ns.cloudflare.com

域名托管到 Cloudflare 后，可以使用 Cloudflare 提供的 DNS 解析、SSL 证书、CDN 加速等功能。

第二种：在 Cloudflare Workers 添加自定义域名

进入部署在 Cloudflare Workers 的项目管理页面，进入 Settings -> Domains & Routers 页面，点击 Add 按钮，选择 Custom Domain，输入你的自定义域名（可以是托管在 Cloudflare 的根域名，或者子域名），点击 Add Domain 按钮，添加自定义域名。

访问项目

上一步添加自定义域名后，Cloudflare 会自动为域名添加到 Cloudflare Workers 的 DNS 解析记录。等 DNS 解析生效（一般半小时内生效，最多可能需要 48 小时），就可以通过自定义域名访问你的项目了。

配置 Hyperdrive

Hyperdrive 是一项由 Cloudflare 提供的，用于加速全球用户对现有数据库访问的服务。

通过以下步骤配置 Hyperdrive，加快 Cloudflare Workers 上部署的项目对外部数据库的访问速度。

2025-12-23 新问题记录

由于咱们使用的是非Cloudflare D1数据库（例如：Supabase），这时候必须配置 Hyperdrive，要不然会遇到：页面异常崩溃问题，在 Cloudflare Workers 环境中 postgres-js 驱动有点问题，

使用Hyperdrive（ Cloudflare 的数据库加速服务），可以解决 postgres-js 在 Workers 环境中的兼容性问题。

配置 Hyperdrive

进入 Cloudflare 控制台，在 Storage & databases -> Hyperdrive 页面点击 Create configuration 按钮，创建 Hyperdrive 配置。

在创建 Hyperdrive 配置页面，选择 Connect to public database，然后填入数据库配置信息。

• Configuration name ：是给你自己看的配置名称，填什么无所谓。

• Connection String ：要填写项目线上环境的数据库连接地址。例如：

复制后改成下面这样：

// 这是复制的示例
postgresql://postgres:[YOUR_PASSWORD]@db.tsjbzbpzwilbxnrqkqzp.supabase.co:5432/postgres

// 下面是修改成的示例：
// 注意：[YOUR_PASSWORD]换成你的密码，
// 注意：db.qcddhntipeafhilqnilm.supabase.co 换成你的
组装示例：postgres://postgres:[YOUR_PASSWORD]@db.qcddhntipeafhilqnilm.supabase.co:5432/postgres

Next创建成功

复制 Hyperdrive 配置 ID

在 Hyperdrive 配置管理页面，复制 Hyperdrive 配置 ID。

打开根目录下.gitignore

打开 你项目根目录下/wrangler.jsonc

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"main": ".open-next/worker.js",
	"name": "shipany-template-mdx-blog,
	"compatibility_date": "2025-12-02",
	"compatibility_flags": ["nodejs_compat"],
	"assets": {
		"directory": ".open-next/assets",
		"binding": "ASSETS"
	},
	"r2_buckets": [
		// Use R2 incremental cache
		// See https://opennext.js.org/cloudflare/caching
		{
			"binding": "NEXT_INC_CACHE_R2_BUCKET",
			// Create the bucket before deploying
			// You can change the bucket name if you want
			// See https://developers.cloudflare.com/workers/wrangler/commands/#r2-bucket-create
			"bucket_name": "cache"
		}
	],
    // ！！！这里是新增hyperdrive配置！！！【可删除掉中文备注】
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE", // 固定值 不要改【可删除掉中文备注】
			"id": "8e25228e46c54xxxxx064e89df2e", // 上面复制的Hyperdrive 配置 ID【可删除掉中文备注】
			"localConnectionString": "postgres://postgres.bobhcicyxxxxsdbvpf:[Your Password]@aws-1-us-west-1.pooler.supabase.com:5432/postgres" // 这个是从Supabase复制过来的，注意格式和我的要一致，端口是5432，其中[Your Password]改成你的数据库密码【可删除掉中文备注】
		}
	],
	//  ！！！这里是开启日志的配置 ！！！【可删除掉中文备注】
	"observability": {
		"enabled": true,
		"head_sampling_rate": 1,
		"logs": {
			"enabled": true,
			"head_sampling_rate": 1,
			"invocation_logs": true
		}
	},
    //  ！！！这里是环境变量的配置 ！！！注意：这个会提交到git上，一定要私有仓库，避免泄露，部分值做了xxx处理【可删除掉中文备注】
	"vars": {
		"NEXT_PUBLIC_APP_URL": "https://xxxx.xxxx.xyz", 
		"NEXT_PUBLIC_APP_NAME":  "Mdx Blog Template",
		"NEXT_PUBLIC_THEME": "default",
		"NEXT_PUBLIC_APPEARANCE": "dark",
		"DATABASE_URL": "postgres://postgres.bobhcicyxxxxsdbvpf:xxxx@aws-1-us-west-1.pooler.supabase.com:5432/postgres",
		"DATABASE_PROVIDER": "postgresql",
		"DB_SINGLETON_ENABLED": "false",
		"DB_MAX_CONNECTIONS": "10",
		"AUTH_SECRET": "wGxL6wMsyxxxxDC0lfRzgl3PzHPMZDAN+s="
	}
}

保存后，提交到git触发自动部署，然后再次访问项目，看下admin能不能正常进入，例如：https://my-shipany.16781678.xyz/admin/users

部署成功后，项目会使用 Hyperdrive 加速数据库访问。可以在 Hyperdrive 管理页面，看到数据查询请求的统计信息。

个人建议配置上，我之前有个站配置后 查询返回明显快了很多