MusicXML 并不是某一家打谱软件私有的工程文件，而是一套开放的、基于 XML 的乐谱描述标准。它的目标是让不同记谱程序之间能够交换完整的音乐信息，包括音符时值、音高、连音线、表情记号、谱表布局甚至页面尺寸。一个典型的 MusicXML 文件以 <score-partwise> 作为根节点，通过 <part> 表示不同声部，再按 <measure> 组织小节，最终在 <note> 里记录音高和时值。理解这个层级关系，是后面做上传、解析和渲染的基础。

MusicXML 的两种结构：partwise 与 timewise

MusicXML 最常用的结构叫 partwise，也就是按声部来遍历。文件先列出所有声部，再依次进入每个声部的小节。这种组织方式与大多数打谱软件内部按声部编辑的习惯一致，所以导出时很常见。比如一个钢琴谱包含两个声部，partwise 结构会先写两个 <score-part> 定义，再分别给每个 <part> 写入连续的小节。解析时，如果你只关心某个声部的旋律，直接取对应的 <part> 节点就行。

另一种是 timewise，它按小节来组织，先收集第 1 小节所有声部的数据，再进入第 2 小节。这种结构在旧版本软件或某些合成工具里偶尔出现，解析时要注意区分根节点名称。两种结构在语义上完全等价，可以通过转换规则互相映射。实际项目中，如果接收的文件规模较大，建议优先兼容 partwise，同时用 DOMParser 或流式解析来做格式探测，避免把整个 XML 一次性读进内存后才发现结构不符。

核心标签与音乐信息

在 <note> 内部，<pitch> 包含 <step> 和 <octave>，前者表示音名，后者表示八度。时值由 <duration> 和 <type> 共同决定，前者是一个相对整数，需要结合 <divisions> 换算成实际长度。比如 <divisions> 为 2 时，四分音符的 duration 就是 2；为 4 时，四分音符则是 4。跨小节的连音线在 <tie> 或 <slur> 中描述，强弱、渐强等记号则放在 <direction> 里。<attributes> 通常出现在小节开头，用来声明谱号、调号和拍号。

这里有一个容易混淆的点：<duration> 的值本身没有固定单位，它只是相对 <divisions> 的一个份数。如果直接把它当成毫秒或 MIDI tick，渲染出来的节奏就会完全错误。解析时必须先读取当前 <attributes> 里的 <divisions>，再除以它才能得到以四分音符为基准的长度。下面这段 XML 片段展示了一个最简单的单声部小节：

<?xml version="1.0" encoding="UTF-8"?>
<score-partwise version="4.0">
  <part-list>
    <score-part id="P1">
      <part-name>Piano</part-name>
    </score-part>
  </part-list>
  <part id="P1">
    <measure number="1">
      <attributes>
        <divisions>1</divisions>
        <key><fifths>0</fifths></key>
        <time><beats>4</beats><beat-type>4</beat-type></time>
        <clef><sign>G</sign><line>2</line></clef>
      </attributes>
      <note>
        <pitch><step>C</step><octave>4</octave></pitch>
        <duration>4</duration>
        <type>whole</type>
      </note>
    </measure>
  </part>
</score-partwise>

这段数据里 <divisions> 为 1，因此全音符的 duration 是 4，表示四个四分音符长度。真实乐谱里 divisions 通常会设成 4 或更大，以支持八分音符、十六分音符等更细的时值。

上传接口与文件存储设计

做一个乐谱分享应用，后端第一步得把文件安全地收下来。MusicXML 文件本质上就是 XML 文本，可以直接存磁盘或对象存储；压缩格式 MXL 其实是 ZIP 包，里面包含 META-INF/container.xml 和乐谱 XML。为了简化，我们先把文件保存在服务器的 uploads 目录，并在数据库记录原始文件名、存储名、上传时间和分享 token。文件名校验不能只看扩展名，因为 .xml 也可能来自其他 XML 数据。

使用 Node.js 配合 multer 可以快速得到可用的上传接口。multer 负责处理 multipart/form-data，通过 diskStorage 把文件落到指定目录，同时用 fileFilter 限制扩展名和大小。下面是一个最小实现，重点在于文件名重命名和中文文件名处理。由于浏览器以 UTF-8 发送文件名时，Node 的 multer 有时会把 originalname 按 latin1 解析，所以拿到后需要手动转回 UTF-8，否则中文标题会变成乱码。

const express = require('express');
const multer = require('multer');
const path = require('path');
const crypto = require('crypto');
const app = express();
const uploadDir = path.join(__dirname, 'uploads');
const storage = multer.diskStorage({
  destination: function (req, file, cb) {
    cb(null, uploadDir);
  },
  filename: function (req, file, cb) {
    const ext = path.extname(file.originalname).toLowerCase();
    const id = crypto.randomBytes(8).toString('hex');
    cb(null, `${id}${ext}`);
  }
});
const fileFilter = function (req, file, cb) {
  const allowed = ['.musicxml', '.xml', '.mxl'];
  const ext = path.extname(file.originalname).toLowerCase();
  if (allowed.includes(ext)) {
    cb(null, true);
  } else {
    cb(new Error('仅支持 MusicXML 或压缩的 MXL 文件'));
  }
};
const upload = multer({
  storage: storage,
  fileFilter: fileFilter,
  limits: { fileSize: 20 * 1024 * 1024 }
});
app.post('/api/scores', upload.single('score'), async (req, res) => {
  if (!req.file) {
    return res.status(400).json({ error: '没有收到文件' });
  }
  const originalName = Buffer.from(req.file.originalname, 'latin1').toString('utf8');
  res.json({
    message: '上传成功',
    fileId: req.file.filename,
    originalName: originalName
  });
});
app.listen(3000, () => {
  console.log('乐谱服务已启动');
});

这个接口返回了 fileId，前端可以用它拼接读取地址。生产环境建议把 uploads 目录放到 Nginx 或 CDN 后面，避免让 Node 直接处理大文件下载。如果使用对象存储，multer 也有对应的 memoryStorage，拿到 Buffer 后调用云厂商 SDK 上传即可。至于 MXL 文件，可以先在后端校验 ZIP 结构，也可以直接存储，由渲染库决定是否支持。

前端解析与渲染：把 XML 变成可交互五线谱

上传完成后，用户最期待的是看到排版正常的五线谱。自己从零解析 MusicXML 并绘制五线谱并不划算，因为连谱表间距、符干方向、临时记号避让这些细节都要考虑。开源库 OpenSheetMusicDisplay 可以接收 MusicXML 字符串，渲染成 SVG 或 Canvas，并且支持缩放和播放光标。前端只要拿到 XML 文本，调用 load 方法即可。

调用前要确认文件编码。MusicXML 通常声明为 UTF-8，但有些 Windows 打谱软件导出的文件可能带 BOM 或使用其他编码。浏览器通过 FileReader 读取为文本时，务必指定 UTF-8，如果出现意外字符，可以用 TextDecoder 处理。渲染时，容器需要一个固定高度，否则 SVG 可能被截断。下面这段代码演示了从文件输入到渲染的完整流程：

import { OpenSheetMusicDisplay } from 'opensheetmusicdisplay';
async function renderScore(xmlText, container) {
  const osmd = new OpenSheetMusicDisplay(container, {
    autoResize: true,
    backend: 'svg'
  });
  await osmd.load(xmlText);
  osmd.render();
}
async function handleFile(file) {
  const xmlText = await file.text();
  const container = document.getElementById('score-container');
  await renderScore(xmlText, container);
}

如果不想引入第三方渲染库，也可以用原生 DOMParser 提取乐谱数据，再用自己熟悉的绘制方案。下面这个解析函数会把所有音符统一抽出来，适合做统计、转调或生成 MIDI 等需求。需要注意 <note> 节点中可能包含休止符，其内部没有 <pitch>，而是用 <rest> 表示。解析时要跳过休止符，或者单独处理休止时值。

const parser = new DOMParser();
const xmlDoc = parser.parseFromString(xmlText, 'application/xml');
const notes = xmlDoc.querySelectorAll('note');
const result = [];
notes.forEach((note) => {
  const pitch = note.querySelector('pitch');
  if (!pitch) return;
  const step = pitch.querySelector('step').textContent;
  const octave = pitch.querySelector('octave').textContent;
  const duration = note.querySelector('duration')?.textContent || '0';
  result.push({
    pitch: step + octave,
    duration: parseInt(duration, 10)
  });
});
console.log(result);

这里有一个细节：querySelectorAll('note') 会命中所有声部的 <note>，如果曲目包含多个声部，需要先获取对应的 <part> 节点再向下查询。否则不同声部的音符合在一起，后续做对齐或播放时就会错位。一般可以先遍历 <part-list> 拿到声部 ID，再逐个处理。

分享链接与权限控制

分享功能的核心是一个不可猜测的短 token。把 token 存在数据库的 share_token 字段，访问时根据 token 查出乐谱路径，再返回对应的 XML 内容或渲染页面。token 生成不要用递增 ID，否则别人改一下数字就能看到其他人的谱子。最简单的方式是用随机字节做 SHA-256，再截取合适长度。下面是一个生成和校验 token 的示例：

const crypto = require('crypto');
function createShareToken(scoreId) {
  const raw = `${scoreId}:${Date.now()}:${crypto.randomBytes(16).toString('hex')}`;
  return crypto.createHash('sha256').update(raw).digest('hex');
}
async function getSharedScore(req, res) {
  const token = req.params.token;
  const row = await db.query(
    'SELECT id, title, xml_path FROM scores WHERE share_token = ?',
    [token]
  );
  if (!row) {
    return res.status(404).json({ error: '分享链接无效' });
  }
  res.json({ id: row.id, title: row.title });
}

数据库表结构可以很精简：scores 表保存 id、title、xml_path、share_token、created_at，users 表保存用户信息。如果要做私有分享，再增加一个 score_permissions 表，记录哪些用户或邮箱可以查看。访问控制建议放在文件读取之前，不能只在前端隐藏按钮，因为分享链接可以直接访问接口。对需要登录才能查看的谱子，后端应校验 session 或 JWT，再决定是否输出文件流。

最后是 MXL 压缩包的处理。如果应用内需要在线预览 MXL，可以后端解压后返回内部的 MusicXML 字符串，或使用支持 MXL 的前端库。解压时注意目录穿越，ZIP 条目可能带有 ../ 路径，必须校验解压后的路径是否仍位于目标目录内，否则可能覆盖服务器文件。这个小细节在乐谱上传分享场景里经常被忽略。

把上面这些流程串起来，一个最小可用的乐谱上传与分享应用就完成了：前端选文件、后端存文件、渲染层显示五线谱、分享时用 token 控制访问。后续如果要做得更完整，可以加入乐谱版本管理、评论标记、导出 PDF 或按声部试听，这些能力都建立在 MusicXML 结构化数据之上。