JSON 与 XML 互转完全指南: 属性映射、数组处理与命名空间的工程级实现

在 2026 年的开发生态中，JSON 已经是事实上的数据交换标准，但 XML 依然在企业级系统中占据不可替代的位置——SOAP API、RSS/Atom 订阅、SAML 认证、Maven/Gradle 构建配置、Android 布局文件，以及海量的遗留系统都在使用 XML 格式。根据 ProgrammableWeb 的统计，全球仍有超过 40% 的公开 API 提供 XML 格式的响应，而在金融、医疗、政府等行业，XML Schema 的严格类型约束甚至是合规要求。当你需要在现代 JSON 微服务和遗留 XML 系统之间架起桥梁时，一个健壮的 JSON↔XML 互转方案就成了刚需。然而，这两种格式的结构差异远比表面看起来大——XML 的属性（Attribute）、命名空间（Namespace）、混合内容（Mixed Content）在 JSON 中没有天然对应，而 JSON 的数组（Array）和 null 在 XML 中也需要特殊处理。本文将从零实现完整的双向转换器，并深入探讨工程实践中容易踩坑的关键问题。

📌 记住： JSON 和 XML 之间的转换不是简单的字段映射，而是一个需要处理语义差异的数据工程问题。选错策略，你的数据可能会在转换过程中"变形"甚至丢失。

🔄 一、JSON 与 XML 的结构差异：映射的核心挑战

在开始编码之前，必须理解这两种格式的根本差异。很多转换 bug 的根源就在于对这些差异认识不足。

1.1 属性 vs 元素：XML 的独特表达

XML 有两种方式表达数据：属性（Attribute） 和 子元素（Child Element）。但 JSON 只有一种方式——键值对。这是一个根本性的映射难题：

<!-- XML：属性和子元素是两种不同的数据表达 -->
<user id="1001" role="admin">
  <name>张三</name>
  <email>zhangsan@example.com</email>
</user>

// JSON：只有键值对一种方式，需要约定来区分属性和元素
{
  "user": {
    "@id": "1001",
    "@role": "admin",
    "name": "张三",
    "email": "zhangsan@example.com"
  }
}

属性在语义上通常表示「元数据」（如 id、type、lang），而子元素表示「内容数据」。但在实际的 XML 文档中，这种边界经常模糊——有些系统把核心数据放在属性里，有些放在子元素里。转换策略的选择会直接影响数据的可逆性。

1.2 数组表示：重复元素 vs JSON 方括号

JSON 用方括号 [] 明确表示数组，但 XML 没有原生的数组概念。XML 中的「数组」通常表现为同名重复元素：

<!-- XML：数组通过重复同名元素表示 -->
<users>
  <user>张三</user>
  <user>李四</user>
  <user>王五</user>
</users>

这里的关键问题是：当同名子元素只有一个时，它到底是对象还是数组？ 如果 users 下只有一个 user，转换后应该得到 { "user": "张三" } 还是 { "user": ["张三"] }？这个看似简单的问题是 JSON↔XML 转换中最常见的 bug 来源。

⚠️ 警告： 单元素数组退化（Array Degradation）是 JSON↔XML 转换中最隐蔽的 Bug。如果不对数组字段做显式标记，转换结果会因为数据量不同而产生不同的结构，导致下游代码崩溃。

1.3 特殊值：null、布尔值与空元素

XML 没有 null、boolean、number 等数据类型——所有值都是字符串。JSON 则有完整的类型系统。转换时需要做类型推断：

💡 提示： 默认开启数值和布尔值自动类型推断（parseTagValue: true）虽然方便，但在某些场景下会导致数据失真。例如邮政编码 "007001" 会被转成数字 7001，前导零丢失。建议对关键字段使用显式的类型标注。

🔧 二、XML 转 JSON：从零实现完整转换器

理解了结构差异后，我们来从零实现一个可用的 XML→JSON 转换器。

2.1 基础实现：DOM 解析 + 递归遍历

最直观的方案是利用浏览器或 Node.js 的 DOM 解析器，将 XML 解析为 DOM 树，然后递归遍历：

// 从零实现 XML 转 JSON 转换器：基于 DOMParser + 递归遍历
// 支持属性映射（@前缀）、文本节点（#text）和自动数组检测

function xmlToJson(xmlString, options = {}) {
  const {
    attributePrefix = '@',      // 属性名前缀
    textNodeName = '#text',     // 文本节点名
    autoArray = true,           // 是否自动检测数组
    parseNumbers = true,        // 是否自动解析数字
    parseBooleans = true,       // 是否自动解析布尔值
    trimValues = true           // 是否去除首尾空白
  } = options;

  const parser = new DOMParser();
  const doc = parser.parseFromString(xmlString, 'application/xml');

  // 检查解析错误
  const parseError = doc.querySelector('parsererror');
  if (parseError) {
    throw new Error(`XML 解析失败: ${parseError.textContent.slice(0, 100)}`);
  }

  // 类型推断：将字符串值转为合适的 JS 类型
  function inferType(value) {
    if (!value || typeof value !== 'string') return value;
    const trimmed = trimValues ? value.trim() : value;
    if (trimmed === '') return '';
    if (parseBooleans && trimmed === 'true') return true;
    if (parseBooleans && trimmed === 'false') return false;
    if (parseNumbers && /^-?\d+(\.\d+)?([eE][+-]?\d+)?$/.test(trimmed)) {
      // 保留前导零的字符串不转数字（如邮编 "007001"）
      if (/^0\d+$/.test(trimmed)) return trimmed;
      return Number(trimmed);
    }
    return trimmed;
  }

  // 递归转换 DOM 节点
  function convertNode(node) {
    const result = {};

    // 处理属性
    if (node.attributes) {
      for (const attr of node.attributes) {
        result[`${attributePrefix}${attr.name}`] = inferType(attr.value);
      }
    }

    // 统计子元素名称（用于数组检测）
    const childElementCounts = {};

    for (const child of node.childNodes) {
      if (child.nodeType === Node.TEXT_NODE || child.nodeType === Node.CDATA_SECTION_NODE) {
        const text = child.textContent;
        const trimmed = trimValues ? text.trim() : text;
        if (trimmed) {
          // 如果只有文本没有属性和子元素，直接返回值
          if (Object.keys(result).length === 0 && node.childNodes.length === 1) {
            return inferType(trimmed);
          }
          result[textNodeName] = inferType(trimmed);
        }
      } else if (child.nodeType === Node.ELEMENT_NODE) {
        const name = child.nodeName;
        childElementCounts[name] = (childElementCounts[name] || 0) + 1;
        const childValue = convertNode(child);

        if (autoArray && childElementCounts[name] > 1) {
          // 多个同名元素 → 数组
          if (!Array.isArray(result[name])) {
            result[name] = [result[name]];
          }
          result[name].push(childValue);
        } else if (autoArray && result[name] !== undefined) {
          // 第二次遇到同名元素，将已有值转为数组
          result[name] = [result[name], childValue];
        } else {
          result[name] = childValue;
        }
      }
    }

    // 空元素返回 null
    if (Object.keys(result).length === 0) {
      return null;
    }

    return result;
  }

  const root = doc.documentElement;
  return { [root.nodeName]: convertNode(root) };
}

这个基础实现支持了属性映射、类型推断和自动数组检测。用一个实际的 XML 测试：

// 测试 XML 转 JSON 转换器
const xml = `<?xml version="1.0" encoding="UTF-8"?>
<catalog>
  <book id="1" category="fiction">
    <title>三体</title>
    <author>刘慈欣</author>
    <price>36.00</price>
    <inStock>true</inStock>
    <tags>
      <tag>科幻</tag>
      <tag>雨果奖</tag>
    </tags>
  </book>
  <book id="2" category="tech">
    <title>JavaScript 高级程序设计</title>
    <author>Nicholas C. Zakas</author>
    <price>129.00</price>
    <inStock>false</inStock>
    <tags>
      <tag>前端</tag>
      <tag>JavaScript</tag>
    </tags>
  </book>
</catalog>`;

const result = xmlToJson(xml);
console.log(JSON.stringify(result, null, 2));
// 输出：完整的 JSON 对象，属性以 @ 为前缀，数值自动解析，布尔值正确转换

2.2 属性处理的三种策略

不同的场景需要不同的属性处理策略。以下是三种主流方案的对比：

// 分离对象法实现：将属性、文本、子元素分别放在不同字段中
// 这种方式保证了 100% 的可逆性，适合需要 XML↔JSON 无损往返转换的场景

function xmlToJsonReversible(xmlString) {
  const parser = new DOMParser();
  const doc = parser.parseFromString(xmlString, 'application/xml');

  function convert(node) {
    const obj = {};
    let hasContent = false;

    // 收集属性
    if (node.attributes && node.attributes.length > 0) {
      obj[':attributes'] = {};
      for (const attr of node.attributes) {
        obj[':attributes'][attr.name] = attr.value;
      }
      hasContent = true;
    }

    // 收集文本
    let textContent = '';
    for (const child of node.childNodes) {
      if (child.nodeType === Node.TEXT_NODE || child.nodeType === Node.CDATA_SECTION_NODE) {
        textContent += child.textContent.trim();
      } else if (child.nodeType === Node.ELEMENT_NODE) {
        hasContent = true;
        const childName = child.nodeName;
        const childValue = convert(child);
        if (obj[childName] !== undefined) {
          if (!Array.isArray(obj[childName])) obj[childName] = [obj[childName]];
          obj[childName].push(childValue);
        } else {
          obj[childName] = childValue;
        }
      }
    }

    if (textContent) {
      obj[':text'] = textContent;
      hasContent = true;
    }

    return hasContent ? obj : textContent || null;
  }

  const root = doc.documentElement;
  return { [root.nodeName]: convert(root) };
}

2.3 数组自动检测的进阶方案

单靠同名元素检测数组是不够的。更健壮的方案是提供显式的数组标记配置：

// 智能数组检测：支持显式配置 + 自动检测 + 路径匹配
// 三种方式结合，彻底解决数组退化问题

class SmartXmlToJsonParser {
  constructor(options = {}) {
    // 显式指定哪些路径下的元素是数组
    // 支持通配符：'*.item' 表示任意层级的 item 都是数组
    this.explicitArrays = new Set(options.alwaysArray || []);
    this.autoDetect = options.autoDetect !== false;
  }

  // 检查某个路径是否应该被标记为数组
  shouldTreatAsArray(path) {
    // 1. 精确匹配
    if (this.explicitArrays.has(path)) return true;

    // 2. 通配符匹配
    for (const pattern of this.explicitArrays) {
      if (pattern.startsWith('*.')) {
        const suffix = pattern.slice(2);
        if (path.endsWith(`.${suffix}`)) return true;
      }
    }

    return false;
  }

  parse(xmlString) {
    const parser = new DOMParser();
    const doc = parser.parseFromString(xmlString, 'application/xml');
    const self = this;

    function convert(node, parentPath = '') {
      const result = {};
      const childCounts = {};

      for (const child of node.childNodes) {
        if (child.nodeType === Node.TEXT_NODE) {
          const text = child.textContent.trim();
          if (text) result['#text'] = text;
        } else if (child.nodeType === Node.ELEMENT_NODE) {
          const name = child.nodeName;
          const currentPath = parentPath ? `${parentPath}.${name}` : name;
          childCounts[name] = (childCounts[name] || 0) + 1;

          const value = convert(child, currentPath);
          const forceArray = self.shouldTreatAsArray(currentPath);

          if (forceArray || (self.autoDetect && childCounts[name] > 1)) {
            if (!Array.isArray(result[name])) {
              result[name] = result[name] !== undefined ? [result[name]] : [];
            }
            result[name].push(value);
          } else {
            result[name] = value;
          }
        }
      }

      // 处理属性
      if (node.attributes) {
        for (const attr of node.attributes) {
          result[`@${attr.name}`] = attr.value;
        }
      }

      return Object.keys(result).length ? result : null;
    }

    const root = doc.documentElement;
    return { [root.nodeName]: convert(root) };
  }
}

// 使用示例：显式指定 item 和 tag 字段始终为数组
const smartParser = new SmartXmlToJsonParser({
  alwaysArray: ['*.item', '*.tag', 'catalog.book']
});

🔧 三、JSON 转 XML：从零实现完整转换器

反向转换（JSON→XML）的挑战不同：需要决定哪些字段变成属性、哪些变成子元素，以及如何处理 JSON 特有的类型。

3.1 基础实现：递归序列化

// 从零实现 JSON 转 XML 转换器
// 支持 @ 前缀属性映射、#text 文本节点、数组展开和特殊字符转义

function jsonToXml(obj, options = {}) {
  const {
    rootName = null,            // 根元素名（不指定则取对象第一个 key）
    attributePrefix = '@',      // 属性名前缀
    textNodeName = '#text',     // 文本节点名
    indent = 2,                 // 缩进空格数
    declaration = true,         // 是否输出 XML 声明
    prettyPrint = true          // 是否美化输出
  } = options;

  const nl = prettyPrint ? '\n' : '';
  const indentStr = prettyPrint ? ' '.repeat(indent) : '';

  // XML 特殊字符转义
  function escapeXml(value) {
    if (typeof value !== 'string') return String(value);
    return value
      .replace(/&/g, '&')
      .replace(/</g, '&lt;')
      .replace(/>/g, '&gt;')
      .replace(/"/g, '&quot;')
      .replace(/'/g, '&apos;');
  }

  // 递归构建 XML 字符串
  function buildXml(node, tagName, level = 0) {
    const pad = indentStr.repeat(level);

    // 处理原始值（string、number、boolean）
    if (node === null || node === undefined) {
      return `${pad}<${tagName}/>${nl}`;
    }
    if (typeof node !== 'object') {
      return `${pad}<${tagName}>${escapeXml(node)}</${tagName}>${nl}`;
    }

    // 处理数组：展开为多个同名元素
    if (Array.isArray(node)) {
      return node.map(item => buildXml(item, tagName, level)).join('');
    }

    // 处理对象：分离属性、文本和子元素
    let attrs = '';
    let textContent = '';
    let children = '';

    for (const [key, value] of Object.entries(node)) {
      if (key.startsWith(attributePrefix)) {
        // 属性：@id → id="value"
        const attrName = key.slice(attributePrefix.length);
        attrs += ` ${attrName}="${escapeXml(value)}"`;
      } else if (key === textNodeName) {
        // 文本节点
        textContent = escapeXml(value);
      } else if (Array.isArray(value)) {
        // 数组：展开为多个同名子元素
        children += value.map(item => buildXml(item, key, level + 1)).join('');
      } else {
        // 普通子元素
        children += buildXml(value, key, level + 1);
      }
    }

    // 组装元素
    if (!textContent && !children) {
      return `${pad}<${tagName}${attrs}/>${nl}`;
    }
    if (textContent && !children) {
      return `${pad}<${tagName}${attrs}>${textContent}</${tagName}>${nl}`;
    }
    return `${pad}<${tagName}${attrs}>${nl}${textContent ? pad + indentStr + textContent + nl : ''}${children}${pad}</${tagName}>${nl}`;
  }

  let xml = '';
  if (declaration) {
    xml += '<?xml version="1.0" encoding="UTF-8"?>' + nl;
  }

  // 确定根元素
  const keys = Object.keys(obj);
  if (rootName) {
    xml += buildXml(obj[rootName] || obj, rootName, 0);
  } else if (keys.length === 1) {
    xml += buildXml(obj[keys[0]], keys[0], 0);
  } else {
    // 多个 key 时需要包装根元素
    xml += buildXml(obj, 'root', 0);
  }

  return xml;
}

使用示例：

// 测试 JSON 转 XML 转换器
const data = {
  user: {
    '@id': '1001',
    '@role': 'admin',
    name: '张三',
    email: 'zhangsan@example.com',
    hobbies: {
      hobby: ['阅读', '编程', '跑步']
    }
  }
};

console.log(jsonToXml(data));
// 输出：
// <?xml version="1.0" encoding="UTF-8"?>
// <user id="1001" role="admin">
//   <name>张三</name>
//   <email>zhangsan@example.com</email>
//   <hobbies>
//     <hobby>阅读</hobby>
//     <hobby>编程</hobby>
//     <hobby>跑步</hobby>
//   </hobbies>
// </user>

3.2 处理 CDATA 与特殊内容

在实际场景中，JSON 值可能包含大量 XML 特殊字符（如 HTML 片段），转义后会变得不可读。CDATA 段是更好的选择：

// 扩展 JSON 转 XML：支持 CDATA 段和混合内容
// 当字段值包含大量 XML 特殊字符时，使用 CDATA 包裹更可读

function jsonToXmlWithCdata(obj, cdataFields = new Set()) {
  function escapeXml(s) {
    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;')
            .replace(/>/g, '&gt;');
  }

  function shouldCdata(fieldName, value) {
    // 自动检测：包含 HTML 标签或大量特殊字符的值使用 CDATA
    if (cdataFields.has(fieldName)) return true;
    if (typeof value === 'string' && (value.includes('<') || value.includes('&'))) {
      return value.length > 20; // 短字符串仍然转义
    }
    return false;
  }

  function build(node, tag, level = 0) {
    const pad = '  '.repeat(level);

    if (node === null || node === undefined) return `${pad}<${tag}/>\n`;
    if (typeof node !== 'object') {
      const val = String(node);
      if (shouldCdata(tag, val)) {
        return `${pad}<${tag}><![CDATA[${val}]]></${tag}>\n`;
      }
      return `${pad}<${tag}>${escapeXml(val)}</${tag}>\n`;
    }
    if (Array.isArray(node)) {
      return node.map(item => build(item, tag, level)).join('');
    }

    let attrs = '';
    let children = '';
    for (const [k, v] of Object.entries(node)) {
      if (k.startsWith('@')) attrs += ` ${k.slice(1)}="${escapeXml(String(v))}"`;
      else if (Array.isArray(v)) children += v.map(i => build(i, k, level + 1)).join('');
      else children += build(v, k, level + 1);
    }

    return children
      ? `${pad}<${tag}${attrs}>\n${children}${pad}</${tag}>\n`
      : `${pad}<${tag}${attrs}/>\n`;
  }

  const keys = Object.keys(obj);
  const rootKey = keys.length === 1 ? keys[0] : 'root';
  return `<?xml version="1.0" encoding="UTF-8"?>\n${build(obj[rootKey] || obj, rootKey)}`;
}

// 使用示例：HTML 内容自动使用 CDATA
const article = {
  article: {
    '@id': '42',
    title: '如何学习 XML',
    content: '<p>XML 是一种<strong>标记语言</strong>，常用于数据交换。</p>'
  }
};
console.log(jsonToXmlWithCdata(article, new Set(['content'])));
// content 字段会自动使用 CDATA 包裹，避免 HTML 标签被转义

📊 四、主流转换库性能对比

在生产环境中，自己实现转换器虽然灵活，但使用成熟的库更省心。以下是 2026 年主流的 JSON↔XML 转换库对比：

⚡ 关键结论： 如果只选一个库，推荐 fast-xml-parser——它同时支持解析和构建，零依赖，浏览器/Node.js 通用，TypeScript 原生支持，且维护活跃（GitHub 3k+ stars）。对于只需要解析的轻量场景，txml 是更好的选择（8KB，速度最快）。

使用 fast-xml-parser 的生产级配置：

// fast-xml-parser 生产级配置：完整的 XML ↔ JSON 双向转换
import { XMLParser, XMLBuilder } from 'fast-xml-parser';

// ===== XML 转 JSON =====
const parser = new XMLParser({
  // 属性处理
  ignoreAttributes: false,           // 不忽略属性
  attributeNamePrefix: '@_',         // 属性名前缀
  allowBooleanAttributes: true,      // 支持布尔属性（如 <input disabled/>）

  // 类型处理
  parseTagValue: true,               // 自动解析标签值的类型
  parseAttributeValue: true,         // 自动解析属性值的类型
  trimValues: true,                  // 去除首尾空白

  // 数组处理：通过回调函数精确控制
  isArray: (name, jpath, isLeafNode, isAttribute) => {
    // 方式 1：根据元素名判断
    const alwaysArray = ['item', 'entry', 'record', 'row', 'user'];
    if (alwaysArray.includes(name)) return true;

    // 方式 2：根据路径判断
    if (jpath.endsWith('.tags.tag')) return true;
    if (jpath.endsWith('.books.book')) return true;

    return false;
  },

  // 处理命名空间
  removeNSPrefix: true,              // 移除命名空间前缀
  processEntities: true,             // 处理 HTML 实体
  htmlEntities: true                 // 支持 HTML 实体解码
});

const xmlData = `<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetUserResponse>
      <user id="1001">
        <name>张三</name>
        <roles>
          <role>admin</role>
          <role>editor</role>
        </roles>
      </user>
    </GetUserResponse>
  </soap:Body>
</soap:Envelope>`;

const jsonObj = parser.parse(xmlData);
console.log(JSON.stringify(jsonObj, null, 2));

// ===== JSON 转 XML =====
const builder = new XMLBuilder({
  ignoreAttributes: false,
  attributeNamePrefix: '@_',
  format: true,                      // 美化输出
  indentBy: '  ',                    // 缩进字符
  suppressEmptyNode: true,           // 空元素自闭合
  suppressBooleanAttributes: false,  // 保留布尔属性的值
  cdataPropName: '__cdata',          // CDATA 字段名
  commentPropName: '__comment',      // 注释字段名
  processEntities: true
});

const xmlOutput = builder.build(jsonObj);
console.log(xmlOutput);

⚠️ 五、常见陷阱与避坑指南

在实际项目中，JSON↔XML 转换有很多隐蔽的坑。以下是我在生产环境中遇到的最常见问题。

5.1 单元素数组退化

这是最经典的问题。当 XML 中的重复元素恰好只有一个时，转换结果会从数组退化为对象：

// ❌ 错误写法：不处理数组退化
// 当 <users> 下只有一个 <user> 时，结果从 ["张三"] 变成了 "张三"
// 下游代码 forEach 会报错！

// ✅ 正确写法：使用 alwaysArray 配置确保关键字段始终为数组
const parser = new XMLParser({
  isArray: (name) => ['user', 'item', 'record'].includes(name)
});

// 或者在转换后手动修复
function ensureArray(obj, paths) {
  for (const path of paths) {
    const parts = path.split('.');
    let current = obj;
    for (let i = 0; i < parts.length - 1; i++) {
      current = current?.[parts[i]];
    }
    const key = parts[parts.length - 1];
    if (current?.[key] !== undefined && !Array.isArray(current[key])) {
      current[key] = [current[key]];
    }
  }
  return obj;
}

5.2 数值与字符串的误判

// ⚠️ 容易出错的场景
// <code>007</code> → 数字 7（前导零丢失！）
// <phone>1e10</phone> → 数字 10000000000（科学计数法误判！）
// <version>1.0.0</version> → 字符串 "1.0.0"（正确，不是数字）
// <hex>0xFF</hex> → 字符串 "0xFF"（正确，但某些库会误转）

// ✅ 推荐做法：对关键字段禁用自动类型推断
const parser = new XMLParser({
  parseTagValue: true,  // 默认开启
  // 但通过 isCDATA 或手动后处理来保护特殊字段
});

// 转换后手动修正已知字段
function postProcessTypes(obj) {
  if (obj.user?.code) obj.user.code = String(obj.user.code).padStart(3, '0');
  if (obj.user?.phone) obj.user.phone = String(obj.user.phone);
  return obj;
}

5.3 命名空间处理

XML 命名空间（Namespace）在 JSON 中没有原生对应。SOAP、SVG、Atom 等 XML 格式大量使用命名空间：

// XML 命名空间示例
// <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
//   <soap:Body>...</soap:Body>
// </soap:Envelope>

// ✅ 策略 1：移除命名空间前缀（推荐，大多数场景）
const parser1 = new XMLParser({ removeNSPrefix: true });
// 结果：{ "Envelope": { "Body": { ... } } }

// ✅ 策略 2：保留命名空间前缀
const parser2 = new XMLParser({ removeNSPrefix: false });
// 结果：{ "soap:Envelope": { "soap:Body": { ... } } }

// ✅ 策略 3：提取命名空间为独立字段
const parser3 = new XMLParser({
  removeNSPrefix: false,
  ignoreAttributes: false,
  attributeNamePrefix: '@_'
});
// xmlns 属性会被提取为 @_xmlns:soap

5.4 编码与乱码问题

在处理中文 XML 文件时，编码问题特别常见：

// ⚠️ 常见编码陷阱

// 1. XML 声明的编码与实际编码不一致
// <?xml version="1.0" encoding="UTF-8"?> 但文件实际是 GBK 编码
// → 解决：用 chardet 检测实际编码后再解码

// 2. 浏览器中 FileReader 读取二进制文件的编码问题
// → 解决：先读为 ArrayBuffer，再用 TextDecoder 指定编码
const reader = new FileReader();
reader.onload = (e) => {
  const buffer = e.target.result;
  // 尝试 UTF-8，如果失败则回退到 GBK
  let text;
  try {
    text = new TextDecoder('utf-8', { fatal: true }).decode(buffer);
  } catch {
    text = new TextDecoder('gbk').decode(buffer);
  }
  const result = xmlToJson(text);
};

// 3. Node.js 中的 Buffer 编码处理
import { detect } from 'chardet';
import fs from 'fs';

const buffer = fs.readFileSync('data.xml');
const encoding = detect(buffer) || 'utf-8';
const xmlString = buffer.toString(encoding);

💡 六、最佳实践与工具推荐

基于以上分析，总结 JSON↔XML 互转的最佳实践：

选型决策树：

• ✅ 需要浏览器端处理 → fast-xml-parser（零依赖，体积小）
• ✅ Node.js 服务端 → fast-xml-parser（功能全面）或 xml2js（成熟稳定）
• ✅ 只需要解析 XML → txml（8KB，速度最快）
• ✅ 需要 jQuery 风格操作 → cheerio（适合 HTML/XML 混合处理）
• ❌ 不要 自己造轮子，除非有特殊需求（如自定义序列化逻辑）

架构建议：

1. ✅ 定义 JSON↔XML 的映射契约（Mapping Contract）：在项目开始时明确属性前缀、数组策略、空值处理方式，并用文档记录
2. ✅ 编写往返测试（Round-trip Test）：JSON → XML → JSON 的结果应与原始 JSON 一致（或有文档化的差异）
3. ✅ 对关键字段禁用自动类型推断：邮编、电话号码、ID 等字段应始终保持字符串
4. ❌ 不要假设 XML 结构是固定的：遗留系统的 XML 结构可能随时变化，做好防御性解析
5. ⚠️ 注意 XML 实体注入（XXE）：在服务端解析不信任的 XML 时，务必禁用外部实体解析

⚠️ 警告： 在服务端解析用户提交的 XML 时，永远不要使用默认配置的 DOMParser 或 libxml2。XML 外部实体注入（XXE）攻击可以读取服务器文件、发起 SSRF 攻击，甚至导致远程代码执行。务必禁用 DTD 和外部实体：new XMLParser({ processEntities: false })。

📋 总结

JSON↔XML 互转看似简单，实则暗藏诸多陷阱。核心要点如下：

1. 属性映射策略决定转换的可逆性——@ 前缀法最通用，分离对象法最严谨
2. 数组退化是最常见的 bug——始终对关键字段配置 alwaysArray
3. 类型推断需要谨慎——数字/布尔值自动转换可能丢失前导零等信息
4. 命名空间需要明确处理策略——移除前缀通常是最安全的选择
5. 编码检测在中文环境下尤为重要——先检测再解码，避免乱码

对于大多数项目，直接使用 fast-xml-parser 并配置好 isArray 回调和 attributeNamePrefix 即可满足需求。只有在有特殊序列化逻辑或极端性能要求时，才需要自建转换器。

⚡ 关键结论： JSON↔XML 转换的核心不是代码实现，而是映射策略的设计。在写第一行代码之前，先用 5 个典型的 XML 样本手动推导出期望的 JSON 结构，再根据这些结构选择或实现转换器。这个前期投入会为你节省大量调试时间。

相关工具推荐：

• 🔧 JSON 格式化工具 — 在线 JSON 格式化、压缩与校验
• 🔧 JSON 校验工具 — 基于 JSON Schema 的数据校验
• 🔧 JSON 转 TypeScript — 从 JSON 数据自动生成 TypeScript 类型定义
• 🔧 XML 转 JSON 在线工具 — 快速在线转换（开发中）