更新记录

1.0.0（2026-08-27）

初始发布

平台兼容性

云端兼容性

阿里云	腾讯云	支付宝云
√	√	√

云函数类插件通用教程

使用云函数类插件的前提是：使用HBuilderX 2.9+

天天uniCloud数据库跨空间迁移工具

用于在两个 uniCloud 服务空间之间复制数据库数据，支持阿里云、腾讯云和支付宝云。插件采用“双云函数 + H5 可视化页面”的方式：源空间云函数只负责分页读取，目标空间云函数只负责分页写入，页面负责调度和展示进度。

适合处理 uniCloud 控制台导出表数量受限、单表数据量较大、目标云函数不能长时间运行的迁移场景。

迁移页面仅在开发环境可用。项目发布到正式环境后，页面会自动禁用，避免把数据库迁移入口暴露给线上用户。

功能

支持按集合迁移数据
支持每页 1 到 200 条数据
支持跳过目标库已有 _id
支持只统计集合数量，不拉取分页数据
支持页面可视化查看整体进度、集合进度、写入数、跳过数、失败数
源空间通过 URL 化云函数提供分页数据
目标空间每次只处理一页数据，避免长时间运行超时

使用顺序

在 HBuilderX 中导入本插件。
将 uni_modules/tt-database-copy/uniCloud/cloudfunctions/database-copy-source 上传到源空间。
给 database-copy-source 配置云函数 URL 化。
在源函数环境变量中配置 MIGRATION_TOKEN。
将 uni_modules/tt-database-copy/uniCloud/cloudfunctions/database-copy-target 上传到目标空间。
执行集合清单生成脚本：node uni_modules/tt-database-copy/scripts/generate-collections.js。
在 pages.json 中注册页面：uni_modules/tt-database-copy/pages/database-copy/database-copy。
运行到 H5，打开迁移页面。
填入源函数 URL、迁移 token、目标云函数名称和批量参数。
先点“只统计”，确认源库数据量正确后再点“开始迁移”。只统计时仅调用 count，不会分页读取实际数据。

集合清单

插件不会内置业务集合名。执行脚本后会从当前项目读取以下目录：

uniCloud-aliyun/database
uniCloud-alipay/database
uniCloud-tcb/database

读取优先级：

init_data.json
db_init.json
*.schema.json

脚本会生成：

uni_modules/tt-database-copy/common/collections.js

迁移页面会优先使用这个文件里的集合名；如果页面中手动填写了“指定集合”，则以手动输入为准。

生成集合清单示例

在项目根目录执行：

node uni_modules/tt-database-copy/scripts/generate-collections.js

也可以在 HBuilderX 中右键插件的 package.json，选择“外部命令”运行：

npm run generate-collections

执行成功后会看到类似输出：

Generated 12 collections:
- aliyun: 12
uni_modules/tt-database-copy/common/collections.js

如果你的项目同时存在多个服务商目录，脚本会合并所有识别到的集合名，并去重排序。

pages.json 配置

在项目 pages.json 的 pages 数组中添加页面：

{
  "path": "uni_modules/tt-database-copy/pages/database-copy/database-copy",
  "style": {
    "enablePullDownRefresh": false,
    "navigationBarTitleText": "数据库迁移"
  }
}

示例：

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    },
    {
      "path": "uni_modules/tt-database-copy/pages/database-copy/database-copy",
      "style": {
        "enablePullDownRefresh": false,
        "navigationBarTitleText": "数据库迁移"
      }
    }
  ]
}

可视化页面

打开 uni_modules/tt-database-copy/pages/database-copy/database-copy 后，页面只调用目标空间的 database-copy-target，不会直接连接数据库。

页面使用 process.env.NODE_ENV === 'development' 做开发环境限制，非开发环境只显示禁用提示，不允许执行统计或迁移。

调用链：

uni_modules/tt-database-copy/pages/database-copy/database-copy
  -> database-copy-target
  -> database-copy-source URL
  -> 源空间数据库

database-copy-target
  -> 目标空间数据库

页面会按集合、分页展示总数、已处理、写入、跳过和失败数量。每次页面只调用目标函数处理一页数据，目标函数不会循环整张表。

页面参数

源函数 URL: 源空间 database-copy-source 的 URL 化地址
迁移 token: 与源函数环境变量 MIGRATION_TOKEN 一致
目标云函数名称: 默认 database-copy-target
每批条数: 默认 50，最大 200
页间停顿 ms: 默认 300
失败重试次数: 默认 2
指定集合: 每行一个集合名，留空时使用页面内置集合列表

页面会自动把源函数 URL、迁移 token、目标云函数名称、批量参数、页间停顿、失败重试次数和跳过已有开关保存到本地 storage。集合输入不会保存，避免临时迁移范围被下次误用。

云函数参数

database-copy-source 支持：

{
  "token": "CHANGE_ME_LONG_RANDOM_TOKEN",
  "action": "count",
  "collection": "work-orders"
}

{
  "token": "CHANGE_ME_LONG_RANDOM_TOKEN",
  "action": "page",
  "collection": "work-orders",
  "skip": 0,
  "limit": 50
}

database-copy-target 支持：

{
  "sourceUrl": "https://YOUR_SOURCE_FUNCTION_URL",
  "token": "CHANGE_ME_LONG_RANDOM_TOKEN",
  "action": "count",
  "collection": "work-orders",
  "batchSize": 50,
  "dryRun": true,
  "skipExisting": true
}

{
  "sourceUrl": "https://YOUR_SOURCE_FUNCTION_URL",
  "token": "CHANGE_ME_LONG_RANDOM_TOKEN",
  "action": "page",
  "collection": "work-orders",
  "skip": 0,
  "batchSize": 50,
  "dryRun": false,
  "skipExisting": true
}

写入策略

skipExisting: true 时，目标库已存在相同 _id 的记录会跳过，不覆盖。

注意

正式迁移前建议暂停源空间写入，避免增量数据遗漏。
目标空间已有数据时，建议保持 skipExisting: true。
插件只迁移数据库记录，不迁移云存储文件、云函数、schema、索引和权限配置。
跨不同服务商迁移时，要分别确认源函数 URL 可以被目标函数访问。
不要把真实 token 或源函数 URL 发布到插件市场。
迁移完成后建议删除源空间 URL 化配置或更换 MIGRATION_TOKEN。
即使页面在正式环境会禁用，也不要把迁移页面加入线上业务菜单。