很多团队最初选择Miro是看中了它成熟的模板生态和流畅的协同体验。但业务一旦接入国产化采购要求，或者需要考虑内网部署、数据合规时，把在线白板迁到BoardMix就成了绕不开的任务。React项目里白板通常不是一个独立页面，而是嵌在需求评审、设计走查、迭代复盘等模块里的核心区域。替换工作不只是换一个URL，还涉及旧板数据导出、组件生命周期处理、事件通信以及权限账号映射。下面按照一次实际迁移的过程来拆解。
迁移前先把Miro里的资产盘点清楚
动手替换之前，先别急着改代码。Miro里沉淀的内容不一定都能自动迁到BoardMix，尤其是评论、计时器、投票插件、第三方应用生成的特殊形状。这些内容如果依赖平台私有协议，导出后可能只剩一个占位图或者直接丢失。建议先让业务负责人确认哪些板子还在活跃使用，哪些只需要归档。然后从Miro后台拉取板子列表，按更新时间过滤出最近90天有改动的板子。
Miro的REST API可以批量导出板子上的条目，返回JSON结构里包含了坐标、尺寸、文本内容、样式等核心信息。下面的脚本演示了如何拉取一个板子的所有便签。实际跑之前需要替换成自己的访问令牌和板子ID，分页参数也要根据条目数量调整。
const BOARD_ID = 'your_miro_board_id';
const TOKEN = 'your_miro_access_token';
async function fetchMiroItems() {
let items = [];
let cursor = null;
do {
const url = `https://api.miro.com/v2/boards/${BOARD_ID}/items?limit=50`
+ (cursor ? `&cursor=${cursor}` : '');
const res = await fetch(url, {
headers: { Authorization: `Bearer ${TOKEN}` }
});
const data = await res.json();
items = items.concat(data.data || []);
cursor = data.cursor;
} while (cursor);
return items;
}
fetchMiroItems().then(items => {
const stickyNotes = items.filter(item => item.type === 'sticky_note');
console.log(JSON.stringify(stickyNotes, null, 2));
});
导出之后不要立刻导入BoardMix。先做一次字段级检查，重点看坐标是否为负数、宽度高度是否缺失、文本内容是否包含Miro特有的变量或表情。因为Miro的坐标原点在画布中心，而BoardMix默认以左上角为原点，直接套用坐标会出现整体偏移。可以在转换脚本里统一加上偏移量，或者保留负数坐标让BoardMix自己处理。另一个容易忽略的是便签颜色，Miro返回的是十六进制颜色值，BoardMix的开放格式也支持类似字段，但需要确认字段名是否一致。
对于评论、线框和自由画笔，当前的通用做法是导出图片后作为背景图贴到BoardMix板子里，再手工补回关键评论。如果团队对评论归档要求不高，可以在迁移窗口期内只迁移便签、图形和框架，评论以导出PDF的形式留存。这样能大幅降低转换复杂度。
在React里封装BoardMix白板容器
原有Miro的嵌入方案通常是在React组件中动态创建<iframe>，通过Miro的JavaScript SDK初始化会话。换成BoardMix后，建议不要直接在各业务页面里写嵌入逻辑，而是封装一个统一的BoardMixBoard组件。这样后续如果再做白板替换或升级SDK，只需要改这一个文件。
BoardMix同样支持通过iframe嵌入在线白板，并且在跨窗口消息上遵循postMessage协议。我们可以在React的useEffect里创建iframe、监听message事件，在收到白板就绪通知后发送访问令牌。下面是一个基础封装，项目中可以根据实际嵌入地址和参数调整。
import { useEffect, useRef } from 'react';
function BoardMixBoard({ boardId, token, height = 600 }) {
const containerRef = useRef(null);
useEffect(() => {
if (!boardId || !token) return;
const iframe = document.createElement('iframe');
iframe.src = `https://boardmix.cn/app/editor/${boardId}?embed=true`;
iframe.style.width = '100%';
iframe.style.height = `${height}px`;
iframe.style.border = 'none';
containerRef.current.appendChild(iframe);
const handleMessage = (event) => {
if (event.origin !== 'https://boardmix.cn') return;
if (event.data && event.data.type === 'boardmix:ready') {
iframe.contentWindow.postMessage({
type: 'boardmix:set-token',
token
}, 'https://boardmix.cn');
}
if (event.data && event.data.type === 'boardmix:content-changed') {
console.log('白板内容发生变化，可在这里同步保存状态');
}
};
window.addEventListener('message', handleMessage);
return () => {
window.removeEventListener('message', handleMessage);
if (iframe.parentNode) {
iframe.parentNode.removeChild(iframe);
}
};
}, [boardId, token, height]);
return <div ref={containerRef} className="boardmix-container" />;
}
export default BoardMixBoard;
这里没有直接写<iframe>标签的原因是要在useEffect清理函数中方便移除节点。React的JSX声明式写法在卸载时也能移除iframe，但无法保证消息监听器先被清理。上面的写法把创建和销毁都放在副作用里，可以避免页面切换后残留postMessage监听。生产环境建议再加上加载失败、空白超时的提示，避免用户看到一块灰色区域。
替换原有Miro组件时，只需要把<MiroBoard boardId={miroId} />改成<BoardMixBoard boardId={boardMixId} token={boardMixToken} />。如果原组件还接收了onReady、onSelectionChange等回调，可以通过封装组件内部的message事件继续向外抛出，业务层不需要大改。
旧板数据映射与批量导入
Miro导出的便签条目包含data.content这样的嵌套结构，而BoardMix的批量导入接口通常希望直接拿到平面结构的text字段。直接塞进去要么被忽略，要么整个批次报错。需要写一个转换函数，把Miro的条目映射成BoardMix能识别的对象。下面这个例子展示了便签的映射逻辑，坐标单位假设双方都是逻辑像素，但实际需要根据画布缩放比例做校准。
const mapMiroStickyToBoardMix = (miroItem) => {
return {
type: 'sticky_note',
x: miroItem.x ?? 0,
y: miroItem.y ?? 0,
width: miroItem.width ?? 180,
height: miroItem.height ?? 120,
text: miroItem.data?.content ?? '',
style: {
fillColor: miroItem.style?.fillColor ?? '#FFF9B1'
}
};
};
const convertMiroExport = (miroItems) => {
return miroItems
.filter(item => item.type === 'sticky_note')
.map(mapMiroStickyToBoardMix);
};
坐标偏移是最容易出问题的地方。Miro画布中心是原点，BoardMix默认左上角是原点。如果直接把Miro的-120,-80这样的坐标传过去，内容会跑到画布外。做法是遍历所有条目，找到最小的x和y，计算偏移量后统一平移。图形之间的相对位置保持不变，整体平移到正坐标区域即可。宽高字段如果没有，不要省略，给一套默认值，否则导入后可能显示成一个小点。
批量导入建议分小批执行，比如每批50个对象。一次塞入上千个对象时，BoardMix的导入接口可能会因为某个对象格式错误而整体失败，排错成本很高。批次之间留一点间隔，前端可以显示进度条，让迁移过程对用户透明。对于无法自动转换的图元，比如思维导图、表格、看板卡片，统一导出为图片，再把图片作为普通元素插入到BoardMix板子中，位置由原来的边界框决定。这样虽然丢失了可编辑性，但至少保留了视觉内容。
权限、协同与回退方案
权限映射不能只做账号层面的对等复制。Miro里可能存在共享链接访问、访客编辑、按工作区分配的成员角色，BoardMix的权限模型可能区分创建者、编辑者、只读成员。迁移前建议先建立一个对照表，明确哪些Miro角色对应BoardMix的哪个角色，哪些外部协作者需要重新邀请。不要直接开放所有人编辑，迁移初期可以先只给核心成员编辑权限，其他成员只读，跑通流程后再放开。
协同方面，两者都支持多人同时编辑，但写入冲突的处理策略不完全相同。如果在React业务里监听了内容变化并触发自动保存，要注意BoardMix的消息事件频率可能比Miro高。可以直接保存状态，但不要在每一次message里都调用后端接口，最好加一个防抖。比如内容变化后等待2秒再写库，减少无意义的请求。同时要在前端保存一份最新版本号，打开板子时对比版本，避免用户看到旧缓存。
过渡期间可以采用双系统并行。新建的板子全部走BoardMix，历史板子只读保留在Miro，用户如果需要修改旧板，先由管理员迁移到BoardMix，再开放编辑。这样不会因为一次切换影响所有历史工作。前端路由上可以用一个配置开关控制白板组件类型，一旦BoardMix出现导出或权限异常，可以快速切回Miro只读模式。切换开关放在配置中心，不要硬编码在React组件里。
最后建议在迁移完成后保留Miro导出文件至少三个月。即便测试阶段没有发现问题，真实使用中可能会遇到某个旧板子的样式错位、文本乱码，保留原始数据可以随时重新转换并覆盖导入。整体迁移周期如果控制在一到两周，对业务的影响基本可控。