六维教程

EdgeOne Makers 迁移指南

你已经把项目部署在 Vercel 或 Cloudflare Pages 上了，用着还行，但发现中国用户访问慢、某些功能受限、或者想要更好的国内访问体验。这时候就涉及到迁移。这篇教你怎么把项目从其他平台搬到 EdgeOne Makers，尽量做到平滑过渡，不影响线上服务。

为什么迁移

先说说迁移的常见原因，帮你判断自己是不是真的需要迁移。

痛点 Vercel Cloudflare Pages EdgeOne Makers
国内访问速度 较慢，服务器在海外 一般，节点覆盖有限 快，亚洲节点密集
免费额度 有限，超了可能被暂停 较宽裕 免费额度充足
函数写法 Vercel Functions Cloudflare Workers Makers Functions
配置文件 vercel.json wrangler.toml edgeone.json
中国区域加速 不支持 不支持 原生支持
Agent 部署 不支持 不支持 原生支持

如果你的用户主要在中国或亚太地区，EdgeOne Makers 的边缘节点覆盖和国内加速是最大优势。另外平台目前处于公测阶段，限制相对较少。

迁移的整体思路

不管从哪个平台迁过来，核心步骤都是一样的:

1. 记录原平台的构建配置(构建命令、输出目录)
2. 迁移配置文件(重定向、请求头等)
3. 迁移函数代码(语法适配)
4. 在 Makers 创建新项目并部署
5. 配置自定义域名
6. 切换 DNS 解析

下面分别讲从 Vercel 和 Cloudflare 迁移的具体操作。

从 Vercel 迁移

第一步: 记录构建配置

登录 Vercel 控制台，找到你的项目，进入 Settings -> General，在 Build and Development Settings 面板里记下两个关键信息:

  • Build Command(构建命令)，比如 npm run build
  • Output Directory(输出目录)，比如 dist 或 build

这两个信息后面在 Makers 创建项目时需要填。

第二步: 迁移配置文件

如果你用了 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"
        }
      ]
    }
  ]
}

迁移到 Makers 的 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"
        }
      ]
    }
  ]
}

主要区别在于 headers 的 source 匹配语法，Vercel 用 /(.*) 这种正则写法，Makers 用 /* 这种通配符写法。其他部分基本一样。

第三步: 迁移函数代码

Vercel Functions 和 Makers Functions 的写法有差异，需要适配。

Vercel 的函数写法:

// Vercel Functions
export const dynamic = 'force-dynamic';

export function POST(request) {
  return new Response('Hello world');
}

Makers 的函数写法:

// Makers Functions
export default function onRequestPost(context) {
  return new Response('Hello world');
}

核心差异:

对比点 Vercel Makers
函数导出方式 导出具名函数(GET/POST) 导出 onRequest 系列函数
请求参数 直接接收 Request 对象 接收 context 对象，包含请求和环境变量
HTTP 方法路由 导出函数名决定方法 onRequestGet/onRequestPost 等
响应方式 Response 对象 Response 对象，写法相同

GET 请求的迁移示例:

// Vercel: GET 请求
export function GET(request) {
  const url = new URL(request.url);
  const name = url.searchParams.get('name');
  return Response.json({ message: `Hello ${name}` });
}

// Makers: GET 请求
export default function onRequestGet(context) {
  const url = new URL(context.request.url);
  const name = url.searchParams.get('name');
  return Response.json({ message: `Hello ${name}` });
}

第四步: 在 Makers 创建项目

  1. 登录腾讯云控制台，进入 Makers
  2. 点创建项目，选择你的 GitHub 仓库
  3. 填入之前记录的构建命令和输出目录
  4. 点开始部署

第五步: 切换域名

这一步要尽量减少停机时间。

  1. 在 Makers 项目设置里添加你的自定义域名，获取 CNAME 记录值
  2. 先去 DNS 服务商那里，把原来指向 Vercel 的记录删掉
  3. 添加新的 CNAME 记录，指向 Makers 提供的值
  4. 等待 DNS 生效(通常几分钟到几小时)

如果你不想有任何停机时间，可以先让 Makers 用默认的 .pages.dev 类域名跑起来验证没问题，再切域名。

从 Cloudflare Pages 迁移

第一步: 对照功能差异

Cloudflare Pages 和 EdgeOne Makers 的功能对应关系:

Cloudflare Pages EdgeOne Makers 说明
Pages 静态托管 Makers 静态托管 基本相同
Pages Functions Makers Functions 语法有差异，需要适配
wrangler.toml edgeone.json 配置文件格式不同
KV 存储 Edge KV 概念相同，API 不同
D1 数据库 无内置数据库 需要对接外部数据库
R2 存储 Blob 存储 概念类似

第二步: 迁移配置文件

Cloudflare Pages 的 _routes.json 和 _headers 文件需要迁移到 edgeone.json:

原来在 Cloudflare 的 _routes.json:

{
  "version": 1,
  "include": ["/api/*"],
  "exclude": ["/static/*"]
}

对应的 edgeone.json 配置:

{
  "routes": {
    "include": ["/api/*"],
    "exclude": ["/static/*"]
  }
}

原来在 Cloudflare 的 _headers 文件:

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff

/assets/*
  Cache-Control: max-age=31536000

迁移到 edgeone.json:

{
  "headers": [
    {
      "source": "/*",
      "headers": [
        {
          "key": "X-Frame-Options",
          "value": "DENY"
        },
        {
          "key": "X-Content-Type-Options",
          "value": "nosniff"
        }
      ]
    },
    {
      "source": "/assets/*",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "max-age=31536000"
        }
      ]
    }
  ]
}

第三步: 迁移函数代码

Cloudflare Pages Functions 和 Makers Functions 的对比:

// Cloudflare Pages Functions
// functions/api/hello.js
export async function onRequestGet(context) {
  const { env, request } = context;
  return Response.json({ message: 'Hello from Cloudflare' });
}
// Makers Functions
// cloud-functions/api/hello.js
export default function onRequestGet(context) {
  const { request } = context;
  return Response.json({ message: 'Hello from Makers' });
}

主要差异:

对比点 Cloudflare Pages Makers
文件位置 functions/ 目录 cloud-functions/ 或 edge-functions/ 目录
导出方式 具名导出 onRequestGet 默认导出 onRequestGet
env 访问 context.env context 对象或环境变量
函数类型 只有 Pages Functions Edge Functions + Cloud Functions

第四步: 处理 KV 存储迁移

如果你在 Cloudflare 用了 KV 存储，迁移到 Makers 的 Edge KV 需要改写 API 调用:

// Cloudflare KV 写入
await env.MY_KV.put('key', 'value');

// Cloudflare KV 读取
const value = await env.MY_KV.get('key');

// Makers Edge KV 写入
await context.storage.put('key', 'value');

// Makers Edge KV 读取
const value = await context.storage.get('key');

具体 API 可能因函数类型不同而有差异，建议参考 Edge KV 的文档确认最新的调用方式。

第五步: 部署和验证

流程和 Vercel 迁移一样，在 Makers 控制台创建项目、关联仓库、配置构建参数、部署。部署成功后切换到域名管理页面配置自定义域名。

迁移检查清单

不管从哪个平台迁移，完成部署后逐项检查:

检查项 操作 状态
页面能正常访问 逐个检查主要页面
重定向规则生效 测试所有重定向路径
自定义请求头生效 用浏览器开发者工具检查响应头
函数正常运行 调用所有 API 接口测试
环境变量正确配置 检查所有环境变量是否迁移
自定义域名绑定 DNS 记录是否指向 Makers
HTTPS 证书 SSL 证书是否正常
静态资源加载 CSS、JS、图片等资源是否 404

回退方案

迁移过程中万一出问题，需要有回退方案。建议迁移期间不要急着删原平台的项目，保留一到两周的观察期。

迁移期间:
- 原平台项目保持运行，不要删除
- DNS 切到 Makers 后持续观察
- 如果有问题，DNS 切回原平台即可恢复
- 观察一到两周确认稳定后，再清理原平台资源

DNS 切换回退很快，通常几分钟就能生效。这比数据丢失或者长时间停机要好得多。

速查卡片

要点 说明
迁移核心步骤 记录配置 -> 迁移配置文件 -> 适配函数代码 -> 部署 -> 切域名
vercel.json 到 edgeone.json 语法相似，headers 的 source 匹配语法不同
Vercel 函数迁移 导出方式从具名函数改为 onRequest 系列函数
Cloudflare 函数迁移 目录从 functions/ 改为 cloud-functions/ 或 edge-functions/
配置对比 Vercel 用 vercel.json，Cloudflare 用 wrangler.toml，Makers 用 edgeone.json
域名切换 先绑 Makers 域名获取 CNAME，再改 DNS 解析
回退策略 保留原平台项目一到两周，出问题直接切回 DNS
迁移后验证 页面、重定向、请求头、函数、环境变量、域名、HTTPS、静态资源
上一篇
EdgeOne Makers IDE 插件与 CodeBuddy
下一篇
EdgeOne Makers 可观测性概览