
摘要: 从 Vercel 迁移到 EdgeOne Makers 需处理四件事:记录构建命令与输出目录、把 vercel.json 的 redirects/rewrites/headers 改写为 edgeone.json、把函数导出改为 onRequest 系列、切换 DNS 的 CNAME 记录。本文给出逐项配置对照与注意事项。
从 Vercel 迁到 EdgeOne Makers 的工作量集中在四处,其中只有函数写法需要改代码:构建命令与输出目录照抄、vercel.json 的重定向与标头配置语法高度相似只需少量调整、函数导出要从 POST(request) 改成 onRequestPost(context)、域名侧删掉 Vercel 的解析记录换成新的 CNAME。静态站点和纯前端项目基本不涉及第三项,改动最小。
进入 Vercel 仪表板找到要迁移的项目,进入 Settings(项目设置)选择 General(通用)选项卡,在 Build and Development Settings(编译与部署设置)面板中记录两项:
参数 | 说明 | 示例 |
|---|---|---|
Build Command | 构建命令 |
|
Output Directory | 输出目录 |
|
这两个值在 EdgeOne Makers 创建项目时直接填入。输出目录填错是迁移后页面白屏或 404 最常见的原因,务必照抄而不是凭印象填。
如果项目用了 vercel.json 配置重定向或自定义标头,需要把这些配置迁移到 edgeone.json。两者语法非常相似。
Vercel 的 vercel.json:
{
"redirects": [
{ "source": "/articles", "destination": "/blog", "statusCode": 301 }
],
"rewrites": [
{ "source": "/assets/*", "destination": "/assets-new/:splat" }
],
"headers": [
{
"source": "/(.*)",
"headers": [
{ "key": "X-Frame-Options", "value": "DENY" },
{ "key": "Cache-Control", "value": "max-age=7200" }
]
},
{
"source": "/assets/*",
"headers": [
{ "key": "Cache-Control", "value": "max-age=31536000" }
]
}
]
}对应的 edgeone.json:
{
"redirects": [
{ "source": "/articles", "destination": "/blog", "statusCode": 301 }
],
"rewrites": [
{ "source": "/assets/*", "destination": "/assets-new/:splat" }
],
"headers": [
{
"source": "/*",
"headers": [
{ "key": "X-Frame-Options", "value": "DENY" },
{ "key": "Cache-Control", "value": "max-age=7200" }
]
},
{
"source": "/assets/*",
"headers": [
{ "key": "Cache-Control", "value": "max-age=31536000" }
]
}
]
}唯一需要留意的差异在 headers 的 source 写法:Vercel 用正则形式 /(.*) 匹配全站,edgeone.json 用通配形式 /*。redirects 与 rewrites 的字段名、statusCode、:splat 占位符写法都一致。
两者配置语法高度相似但可能存在细微差别,迁移后建议逐条验证重定向是否生效。
edgeone.json 对各类配置有数量与长度限制,迁移前核对 Vercel 侧的配置规模:
项 | 限制 |
|---|---|
redirects 最大数 | 100 |
redirects 的 source / destination 长度 | 不超过 500 字符 |
rewrites 最大数 | 100 |
rewrites 的 source / destination 长度 | 不超过 500 字符 |
headers 最大数 | 30 |
headers 的 key 长度 | 1~100 字符,支持数字、字母、连字符 |
headers 的 value 长度 | 1~1000 字符,不支持中文 |
headers 上限 30 条是三项中最紧的。如果 Vercel 侧按路径细分了大量标头规则,迁移时需要合并同类项——用更宽的 source 匹配规则覆盖多个路径,而不是逐路径配置。
这是唯一需要改业务代码的地方。两个平台在语法和使用方式上有差异。
Vercel Functions 的 Hello World:
export const dynamic = 'force-dynamic';
export function POST(request) {
return new Response(`Hello world`);
}Makers Functions 的 Hello World:
export default function onRequestPost(context) {
return new Response(`Hello world`);
}三个主要差异:
Makers 使用 onRequest 系列函数处理不同的 HTTP 方法,例如 onRequestPost 对应 POST 请求。
Makers Functions 接收一个 context 对象,其中包含请求信息、环境变量等。Vercel 则直接接收 request。
响应方式类似,两者都使用 Response 对象,这部分代码可以原样保留。
迁移操作:把导出函数改为 onRequest 系列函数,并把原先从 request 取请求信息的代码改为从 context 取。
一个需要提前评估的风险:如果项目用了 Vercel 特有的功能,可能需要寻找其他方案,这类情况建议通过社群联系官方确认。
Makers Functions 支持 Cloud Functions 与 Edge Functions 两类,两者在特性上有差异(例如 context 对象的内容),迁移时需要按原函数的实际用途选择。
原 Vercel 函数的特征 | 建议迁移到 |
|---|---|
轻量请求处理、鉴权、重定向、仅用 JavaScript | Edge Functions |
需要完整后端语言生态、连数据库、SSR 渲染 | Cloud Functions |
执行时间较长(超过几十秒) | Cloud Functions(最长可配至 120 秒) |
依赖体积较大 | Cloud Functions(代码包含依赖 128 MB) |
两类函数的关键限制对照:
项 | Edge Functions | Cloud Functions |
|---|---|---|
支持语言 | JavaScript | 多种主流语言与运行时,含 Python、Go |
代码包大小 | 5 MB | 128 MB(含依赖) |
请求 body 大小 | 1 MB | 6 MB |
执行次数(免费版) | 300 万/月 | 100 万/月 |
最大执行时长 | 按 CPU Time 计量 | 默认 30 秒,可配置至 120 秒 |
代码包 5 MB 是选 Edge Functions 时最容易撞的限制。Vercel 上跑得动的函数如果带了较大依赖,迁到 Edge Functions 可能装不下,这种情况走 Cloud Functions。
准备工作完成后:
Git 平台除 GitHub 外还支持 Gitee、Coding、GitLab、Bitbucket。导入后对生产分支(默认 main)的提交会自动触发新部署,这一点与 Vercel 的行为一致。
部署失败时按构建日志的失败步骤定位——构建过程被细分为多个步骤,能看出是依赖安装、构建命令还是产物目录的问题。
迁移步骤:
一个特殊情况:如果之前使用 Vercel DNS,需要先将域名转移到其他 DNS 服务商,再按上述步骤配置 CNAME 记录。
域名侧的配额与能力:免费版支持 200 个自定义域名并提供免费 SSL 证书,归属权验证支持 DNS 解析验证、文件验证等方式,证书可通过自动验证、DNS 委派验证、文件验证等方式申请,域名管理中可设置是否强制 HTTPS。
一个独立于平台的合规要求:域名要服务中国大陆用户需按规定完成 ICP 备案,这是国家法规要求,与托管平台无关。这一点与原先托管在海外平台时的情况不同,需要提前安排时间。
按顺序执行,每项都有明确的验证方式:
顺序 | 操作 | 验证方式 |
|---|---|---|
1 | 记录 Vercel 的 Build Command 与 Output Directory | 两个值抄录完整 |
2 | 把 vercel.json 改写为 edgeone.json,注意 headers 的 source 写法 | 配置条数未超限(redirects/rewrites 各 100,headers 30) |
3 | 把函数导出改为 onRequest 系列,入参改为 context | 本地跑通 |
4 | 选定每个函数走 Edge 还是 Cloud Functions | 代码包与执行时长在对应限制内 |
5 | 在 Makers 创建项目、导入仓库、填入构建参数并部署 | 构建成功且默认 URL 可访问 |
6 | 添加自定义域名获取 CNAME 值 | 控制台显示待验证 |
7 | DNS 侧删除 Vercel 旧记录、添加新 CNAME | 解析生效后域名可访问 |
8 | 申请免费证书、开启强制 HTTPS | HTTPS 访问正常 |
9 | 服务中国大陆用户的域名完成 ICP 备案 | 备案通过 |
建议的切换方式:第 5 步部署成功后先用平台默认 URL 完整验证一遍功能,确认无误再做第 7 步的 DNS 切换,避免线上出现中断窗口。
Vercel 到 EdgeOne Makers 的迁移路径是四块工作:抄两个构建参数、改写配置文件(语法相似,注意 headers 的 source 从 /(.*) 改为 /* 且上限 30 条)、改函数写法(POST(request) 改为 onRequestPost(context))、切 DNS 记录。
三个容易出问题的点:输出目录没照抄导致部署后白屏;Edge Functions 的 5 MB 代码包装不下原有依赖;域名服务中国大陆用户需要完成 ICP 备案,这项需要预留时间。
官方迁移指南同时覆盖从 Cloudflare Pages 和 Netlify 迁入,思路一致,差异主要在配置文件语法与函数签名。
产品完整能力与控制台入口见 EdgeOne Makers 产品页:https://cloud.tencent.com/product/makers
当前首购特惠 EdgeOne Makers 专业版 Pro 套餐 39 元/月,具体以活动页实际展示为准:https://cloud.tencent.com/act/pro/makers-pro
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。