Node脚本用JSZip解析XMind转Markdown并提取图片

脚本专家

把 .xmind 思维导图批量整理成 Markdown 是常见需求，但很多人会误以为 xmind 是某种私有二进制格式。实际上它就是一个 ZIP 压缩包：改扩展名为 .zip 即可解开，旧版 XMind 的导图结构存放在 content.xml，新版 XMind Zen 则是 content.json，附件图片位于 attachments/ 目录，此外还有 Thumbnails/、Revisions/ 这类与正文无关的条目。基于这个事实，本文用 Node.js 配合 JSZip 与 fast-xml-parser，把 content.xml 解析成对象树，再递归映射为 Markdown 无序列表，同时把导图中引用到的图片落地到 md 同级 images/ 目录，用相对路径引用。

一、技术栈与依赖安装

运行时只需要 Node.js（原文环境为 v20.20.2），不依赖 Python。核心库两个：JSZip 负责在内存里把 .xmind 当 ZIP 读取并取出图片字节；fast-xml-parser 负责把 content.xml 解析为 JavaScript 对象树。文件读写、路径拼接、递归建目录则用 Node 内置的 fs 与 path。安装命令：

2. npm install jszip fast-xml-parser

复制代码

二、content.xml 的树形结构与映射规则

导图在数学上是一棵树，XML 通过嵌套标签表达层级：xmap-content 下可有多个 sheet，每个 sheet 下的 topic 是根主题，根主题包含 title、notes、labels、children 等子节点，子主题挂在 children.topics 下，其中 topics 带有 type="attached" 属性，topic 数组层层递归。图片在 xmind 中表现为一个“图片主题”，内部是 xhtml:img 标签：

2. <topic id="...">
3.   <xhtml:img xhtml:src="xap:attachments/767o3sb2dkk7gkj64ckn5ic077.png" .../>
4. </topic>

复制代码

注意 xap: 只是 XML 命名空间前缀，并不是真实路径，去掉后 attachments/xxx.png 才是 ZIP 内部图片的实际地址。

映射到 Markdown 的规则为：根主题输出为一级标题，并去掉冗余的 SystemAnalyst- 前缀；一级及以下主题用嵌套无序列表表示，以两空格缩进表达层级；notes 笔记缩进一级后逐行输出为 > 引用块；labels 标签在行尾追加；图片主题输出为  的相对路径形式，纯图片且无标题的节点直接用图片语法作为列表项。图片统一写成 images/文件名，图片文件放在 md 同级目录的 images/ 中，这样 md 移动到哪、只要 images/ 一起移动，引用就一直有效。

三、核心实现

1. 用 JSZip 在内存中读取 XML

把 xmind 当普通 zip 载入，读回 content.xml 字符串，全程不落中间解压文件，干净且高效：

2. const JSZip = require('jszip');
3. const data = fs.readFileSync(xmindPath);
4. const zip = await JSZip.loadAsync(data);
5. const xml = await zip.file('content.xml').async('string');

复制代码

2. fast-xml-parser 的关键配置

2. const { XMLParser } = require('fast-xml-parser');
3. const parser = new XMLParser({
4.   ignoreAttributes: false,
5.   attributeNamePrefix: '@_',
6.   isArray: (name) => ['topic','topics','sheet','label'].includes(name),
7.   textNodeName: '#text'
8. });

复制代码

其中 isArray 是最重要的一项。fast-xml-parser 默认的返回策略是“只有一个子节点时给对象、多个时给数组”，一旦节点数量变化，递归代码就会因为类型不一致而崩溃。强制 topic、topics、sheet、label 永远返回数组后，遍历逻辑才稳定。ignoreAttributes 必须为 false 才能拿到 type="attached" 这类属性，attributeNamePrefix 给属性名加 @_ 前缀便于和子节点区分。解析后的访问路径大致是：

2. parsed['xmap-content'].sheet[i].topic[j]
3.   .children.topics[k].topic[m]

复制代码

3. 递归生成 Markdown

walkTopic 是转换的核心，靠 depth 参数控制缩进（' '.repeat(depth) 生成两空格层级），靠 parentTitle 把父标题传给子节点，供图片主题生成 alt 文本时使用。标题内的换行会折叠为单个空格，避免破坏 Markdown 列表结构：

2. function walkTopic(topic, depth, out, isRoot, parentTitle, imagesMap, usedImages) {
3.   const originalTitle = txt(topic.title).replace(/\s*\n\s*/g, ' ').trim();
4.   const imgs = findImg(topic);
5.   let isImageOnly = false;
6.   let title = originalTitle;
7.   let hasContent = true;
8.   if (!title) {
9.     if (imgs.length) {
10.       isImageOnly = true;
11.       title = imgs.map(n => imgMd(n, parentTitle, imagesMap, usedImages)).join(' ');
12.     } else {
13.       hasContent = false;
14.     }
15.   }
16.   if (isRoot) {
17.     if (title.startsWith('SystemAnalyst-')) title = title.slice('SystemAnalyst-'.length);
18.     if (title) out.push('# ' + title + '\n');
19.   } else if (hasContent) {
20.     let line = ' '.repeat(depth) + '- ' + title;
21.     const labels = getLabels(topic);
22.     if (labels.length) line += ' `[' + labels.join(', ') + ']`';
23.     out.push(line);
24.   }
25.   const notes = getNotes(topic);
26.   if (notes) {
27.     const ind = isRoot ? 0 : (hasContent ? depth + 1 : depth);
28.     for (const ln of notes.split('\n')) out.push(' '.repeat(ind) + '> ' + ln.trim());
29.   }
30.   if (imgs.length && !isImageOnly) {
31.     const ind = isRoot ? 1 : depth + 1;
32.     const alt = originalTitle || parentTitle || '图片';
33.     for (const n of imgs) {
34.       out.push(' '.repeat(ind) + '- ' + imgMd(n, alt, imagesMap, usedImages));
35.     }
36.   }
37.   const children = topic.children;
38.   if (children && children.topics) {
39.     for (const tn of children.topics) {
40.       const subs = tn.topic || [];
41.       const childDepth = isRoot ? 0 : (hasContent ? depth + 1 : depth);
42.       const nextParent = (title && !isImageOnly) ? title : parentTitle;
43.       for (const c of subs) walkTopic(c, childDepth, out, false, nextParent, imagesMap, usedImages);
44.     }
45.   }
46. }

复制代码

4. 图片映射与落地

先扫描 zip 建立“文件名 → 内部完整路径”的映射，并排除缩略图与历史版本：

2. function buildImageMap(zip) {
3.   const map = new Map();
4.   for (const name of Object.keys(zip.files)) {
5.     const entry = zip.files[name];
6.     if (entry.dir) continue;
7.     if (/Thumbnails|Revisions/i.test(name)) continue;
8.     if (/\.(png|jpe?g|gif|svg|webp|bmp)$/i.test(name)) {
9.       map.set(name.split('/').pop(), name);
10.     }
11.   }
12.   return map;
13. }

复制代码

转换完成后，只把本文件实际引用到的图片写出到 images/：

2. fs.mkdirSync(imgDir, { recursive: true });
3. for (const n of usedImages) {
4.   const internal = imagesMap.get(n);
5.   if (internal) {
6.     const buf = await zip.file(internal).async('nodebuffer');
7.     fs.writeFileSync(path.join(imgDir, n), buf);
8.   }
9. }

复制代码

而图片主题转 Markdown 引用的函数里，一旦命中映射就把文件名记入 usedImages 集合，命不中则降级为占位文本：

2. function imgMd(name, alt, imagesMap, usedImages) {
3.   if (imagesMap.has(name)) {
4.     usedImages.add(name);
5.     return '';
6.   }
7.   return '[图片: ' + name + ']';
8. }

复制代码

5. 边界与降级处理

批量转换最怕一个坏节点拖垮整批，脚本做了几处兜底：图片在 zip 中找不到时输出 [图片: 文件名] 占位，不中断任务；无标题且非图片的空节点不输出自身但保留子结构，层级不丢失；xap:attachments/xxx.png 通过取 / 后段得到真实文件名再回 attachments/ 查找，绕开命名空间前缀干扰；sheet 被强制为数组后循环处理每个画布；Thumbnails/、Revisions/ 下的图片不提取，避免噪声；最后用正则把连续空行压缩为空行、首尾 trim。

四、完整脚本

2. const fs = require('fs');
3. const path = require('path');
4. const JSZip = require('jszip');
5. const { XMLParser } = require('fast-xml-parser');
7. const parser = new XMLParser({
8.   ignoreAttributes: false,
9.   attributeNamePrefix: '@_',
10.   isArray: (name) => ['topic','topics','sheet','label'].includes(name),
11.   textNodeName: '#text'
12. });
14. function txt(node) {
15.   if (node == null) return '';
16.   if (typeof node === 'string') return node;
17.   if (typeof node === 'number') return String(node);
18.   if (Array.isArray(node)) return node.map(txt).join('');
19.   if (typeof node === 'object') {
20.     if ('#text' in node) return txt(node['#text']);
21.     if (node.div || node.p || node.span) return untag(node);
22.     return '';
23.   }
24.   return '';
25. }
27. function untag(node) {
28.   if (node == null) return '';
29.   if (typeof node === 'string') return node;
30.   if (Array.isArray(node)) return node.map(untag).join('');
31.   if (typeof node === 'object') {
32.     let s = '';
33.     for (const k of Object.keys(node)) {
34.       if (k.startsWith('@_')) continue;
35.       if (k === 'br') { s += '\n'; continue; }
36.       if (k === '#text') { s += node[k]; continue; }
37.       s += untag(node[k]);
38.     }
39.     return s;
40.   }
41.   return '';
42. }
44. function findImg(topic) {
45.   if (!topic) return [];
46.   const imgs = topic['xhtml:img'];
47.   if (!imgs) return [];
48.   const arr = Array.isArray(imgs) ? imgs : [imgs];
49.   return arr.map(i => {
50.     const src = i['@_xhtml:src'] || i['@_src'] || '';
51.     return src.split('/').pop() || '';
52.   }).filter(Boolean);
53. }
55. function getNotes(topic) {
56.   const notes = topic && topic.notes;
57.   if (!notes) return '';
58.   if (typeof notes === 'string') return notes.trim();
59.   if (notes.html) return untag(notes.html).trim();
60.   return untag(notes).trim();
61. }
63. function getLabels(topic) {
64.   const labels = topic && topic.labels;
65.   if (!labels) return [];
66.   if (labels.label) return labels.label.map(t => txt(t)).filter(Boolean);
67.   return [];
68. }
70. function imgMd(name, alt, imagesMap, usedImages) {
71.   if (imagesMap.has(name)) {
72.     usedImages.add(name);
73.     return '';
74.   }
75.   return '[图片: ' + name + ']';
76. }
78. function walkTopic(topic, depth, out, isRoot, parentTitle, imagesMap, usedImages) {
79.   const originalTitle = txt(topic.title).replace(/\s*\n\s*/g, ' ').trim();
80.   const imgs = findImg(topic);
81.   let isImageOnly = false;
82.   let title = originalTitle;
83.   let hasContent = true;
84.   if (!title) {
85.     if (imgs.length) {
86.       isImageOnly = true;
87.       title = imgs.map(n => imgMd(n, parentTitle, imagesMap, usedImages)).join(' ');
88.     } else {
89.       hasContent = false;
90.     }
91.   }
92.   if (isRoot) {
93.     if (title.startsWith('SystemAnalyst-')) title = title.slice('SystemAnalyst-'.length);
94.     if (title) out.push('# ' + title + '\n');
95.   } else if (hasContent) {
96.     let line = ' '.repeat(depth) + '- ' + title;
97.     const labels = getLabels(topic);
98.     if (labels.length) line += ' `[' + labels.join(', ') + ']`';
99.     out.push(line);
100.   }
101.   const notes = getNotes(topic);
102.   if (notes) {
103.     const ind = isRoot ? 0 : (hasContent ? depth + 1 : depth);
104.     for (const ln of notes.split('\n')) out.push(' '.repeat(ind) + '> ' + ln.trim());
105.   }
106.   if (imgs.length && !isImageOnly) {
107.     const ind = isRoot ? 1 : depth + 1;
108.     const alt = originalTitle || parentTitle || '图片';
109.     for (const n of imgs) {
110.       out.push(' '.repeat(ind) + '- ' + imgMd(n, alt, imagesMap, usedImages));
111.     }
112.   }
113.   const children = topic.children;
114.   if (children && children.topics) {
115.     for (const tn of children.topics) {
116.       const subs = tn.topic || [];
117.       const childDepth = isRoot ? 0 : (hasContent ? depth + 1 : depth);
118.       const nextParent = (title && !isImageOnly) ? title : parentTitle;
119.       for (const c of subs) walkTopic(c, childDepth, out, false, nextParent, imagesMap, usedImages);
120.     }
121.   }
122. }
124. function buildImageMap(zip) {
125.   const map = new Map();
126.   for (const name of Object.keys(zip.files)) {
127.     const entry = zip.files[name];
128.     if (entry.dir) continue;
129.     if (/Thumbnails|Revisions/i.test(name)) continue;
130.     if (/\.(png|jpe?g|gif|svg|webp|bmp)$/i.test(name)) {
131.       map.set(name.split('/').pop(), name);
132.     }
133.   }
134.   return map;
135. }
137. function convert(xml, imagesMap, usedImages) {
138.   const parsed = parser.parse(xml);
139.   const content = parsed['xmap-content'] || parsed['map'];
140.   const sheets = content.sheet || [];
141.   const md = [];
142.   for (const sheet of sheets) {
143.     const rootTopics = sheet.topic || [];
144.     for (const root of rootTopics) walkTopic(root, 0, md, true, '', imagesMap, usedImages);
145.     md.push('');
146.   }
147.   return md.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\n{2,}$/, '\n').trim() + '\n';
148. }
150. async function main() {
151.   const base = "c:/workspace/gitee/system-analyst-xmind/systemAnalyst";
152.   const dirs = ['案例分析', '综合知识', '论文'];
153.   let count = 0, imgCount = 0;
154.   for (const d of dirs) {
155.     const dp = path.join(base, d);
156.     for (const f of fs.readdirSync(dp)) {
157.       if (!f.toLowerCase().endsWith('.xmind')) continue;
158.       const full = path.join(dp, f);
159.       const data = fs.readFileSync(full);
160.       const zip = await JSZip.loadAsync(data);
161.       const cxml = zip.file('content.xml');
162.       if (!cxml) { console.log('SKIP (no content.xml):', f); continue; }
163.       const xml = await cxml.async('string');
164.       const imagesMap = buildImageMap(zip);
165.       const usedImages = new Set();
166.       const md = convert(xml, imagesMap, usedImages);
167.       const outPath = path.join(dp, f.replace(/\.xmind$/i, '.md'));
168.       fs.writeFileSync(outPath, md, 'utf-8');
169.       if (usedImages.size) {
170.         const imgDir = path.join(dp, 'images');
171.         fs.mkdirSync(imgDir, { recursive: true });
172.         for (const n of usedImages) {
173.           const internal = imagesMap.get(n);
174.           if (internal) {
175.             const buf = await zip.file(internal).async('nodebuffer');
176.             fs.writeFileSync(path.join(imgDir, n), buf);
177.             imgCount++;
178.           }
179.         }
180.       }
181.       count++;
182.       console.log('OK', path.relative(base, outPath), '| 图片:', usedImages.size);
183.     }
184.   }
185.   console.log('Converted', count, 'files, extracted', imgCount, 'images.');
186. }
188. main().catch(e => { console.error(e); process.exit(1); });

复制代码

五、使用方法

把脚本放在分类目录下，直接执行 node xmind2md.js 即可。脚本会遍历 base 与 dirs 指定的子目录，把所有 .xmind 重新生成 .md 并刷新 images/，已生成文件会被覆盖。新增导图时，把新的 .xmind 放进对应目录再跑一次命令，不需要改脚本。如果 node_modules/ 被清理，重新执行 npm install jszip fast-xml-parser 即可。

六、扩展与已知限制

若将来遇到新版 XMind 的 content.json，可以在 main 中优先尝试读取 content.json，再写一套对应的 walkTopicJson（结构为 root.children.attached[] 数组），与现有 XML 分支并存。需要严格标题层级时，可在 walkTopic 中按 depth 切换 # 的数量，但 Markdown 标题最多 6 级，超出仍应退回列表。当前所有图片集中在各分类目录的 images/ 下，如需按单个 xmind 分目录，只要改 imgDir 的拼接逻辑。base 与 dirs 目前写死在脚本内，可改成命令行参数以适配其他目录。

需要说明的限制也有几条：脚本只支持 content.xml 旧版格式；图片按 xmind 生成的随机文件名保存，可读性较弱，想语义化命名需要额外的映射；同一分类目录下若不同 xmind 产生同名图片会被后写入者覆盖，好在随机名重复概率极低，实际未发生；导图中的浮动主题（detached）与关系线等高级元素未纳入转换，仅处理 attached 主分支结构。

热心网友6

这套思路挺实用的，把 .xmind 当成 ZIP 直接读取再递归处理，比依赖专门解析库更灵活；改一个版本也能沿用。几个实践中容易踩到的问题，供参考： 一是版本差异建议先探测再解析。打开 ZIP 后，可以先检查有没有 content.xml，没有的话再看有没有 content.json，不要固定只读其中一个；否则拿到新版 XMind 直接解析成 undefined，报错位置会很难查。 二是图片路径的命名空间前缀既要处理 xap:，也要考虑其他变体。有些文件导出的 src 会带绝对路径或者不同前缀，比较稳妥的做法是只取 attachments/ 之后的部分作为 ZIP 内部路径，再用它去 zip.file 里定位；拼输出文件名时按 ZIP 内原始路径做一次映射，同时用 Set 记录已复制的图片，避免同一张图被多个主题引用时反复写入。 三是同名覆盖问题。不同 sheet 或不同文件夹下可能出现相同文件名的图片，直接取 basename 容易互相覆盖。可以在落地文件名里加一段短哈希，或者保留子目录结构，但映射表要跟着一起改。 四是 content.json 那条分支的遍历逻辑和 XML 不太一样，JSON 里 topic 的子节点直接是 children.attached 数组，处理时最好单独写一层适配，把两种结构归一成同一种内部节点再交给 walkTopic，主逻辑就不用改两遍。 五是

热心网友6

思路很实用，把 xmind 当成 zip 来读确实能绕开很多“私有格式”的误解，而且全程内存解压、不落中间文件这点对批量处理很友好。几个技术点讲得也清楚，尤其是 isArray 那个坑，fast-xml-parser 默认单子节点给对象、多子节点给数组，递归里类型一变就很容易崩，强制 topic、topics、sheet 返回数组是稳的做法；xap: 只是命名空间前缀、去掉后才是 attachments/ 真实路径这个提醒也很关键，很多人会在这里卡住。 图片统一落到 md 同级的 images/ 并用相对路径引用，迁移时整体带走就能一直有效，这个设计比散落引用靠谱。notes 缩进一级转引用块、labels 行尾追加的映射规则也比较符合 Markdown 阅读习惯。 有两点想补充交流一下：一是帖子里提到新版 XMind Zen 是 content.json，但核心实现目前只读了 content.xml，批量跑目录时如果混入 Zen 文件可能会直接报错，建议先判断 zip 里有没有 content.xml，没有就走 content.json 分支或者给出跳过提示。二是 attachments/ 里可能有未被导图引用的图片，按 usedImages 集合只复制实际引用到的文件会更干净，同时留意不同附件重名的情况，落到 images/ 前最好做一次去重或改名，避免后写覆盖前写。 另外 w

热心网友6

思路挺实用的。之前我总觉得 xmind 得靠专用库或者客户端才能读，没想到本质就是 zip，改后缀直接解开这招最直观，也省了装一堆依赖。 关于 content.xml 和 content.json 两个版本，这点提得很关键；但示例里直接调用 zip.file('content.xml')，碰到 XMind Zen 或更新的文件会返回 null，后面再 .async 就直接抛错了。建议先探测一下 content.xml 存不存在，没有再走 content.json 那条路；或者先用 file(/content\.(xml|json)/) 判断再分派，报错信息也能友好点。 isArray 那段说到点上了。fast-xml-parser 默认单子节点给对象，确实最容易踩坑，尤其 topic 数量刚好从 1 变 2 的时候，代码突然就崩。顺手提一句，新版 isArray 的回调签名是 (tagName, jPath, isLeafNode, isAttribute)，用 jPath 判断比如 xxx.children.topics.topic 会更准，能避免别处同名标签被误判成数组。 xap: 前缀这个提醒也很关键，很多人就卡在找不到图片。不过如果 src 里带空格或中文，最好先 decodeURIComponent 再拼 ZIP 内路径，不然 zip.file 找不到。输出到 Markd