8个代码片段玩转SVG文本路径：让文字沿任意曲线排列

一篇做前端的，很少有不跟文本路径打交道的时刻，只是很多人没意识到它叫文本路径而已。你把标题排成一道弧线，做成圆环 Logo，或者让一句话沿着一条不规则波浪线展开，这都不是 CSS 的 flex 或者 grid 能直接解决的问题。CSS、JavaScript、文本路径这几个词放在一起，真正的主角其实是 SVG 的 <textPath>，JavaScript 负责动态生成路径、控制动画和交互。这篇文章我会把一路摸索下来最实用的 8 个代码片段整理出来，每个都能单独粘贴到项目里跑，也会解释到底为什么要这么写，方便你根据自己的场景改出想要的效果。

想动手的读者也不用有压力，不需要背 SVG 语法，只要照着片段复制，再把路径和文字内容换掉就行。更适合谁看呢？一个是做活动页、宣传 Banner、个人主页设计的前端；另一个是刚接触 SVG 动效、想给静态页面加点质感的初学者。下面我先从原理上理一遍文本路径的结构关系，再进入真正的片段实战。

1. 文本路径这件事，到底应该归谁管

CSS 里处理文本对齐有整排、两端对齐，JavaScript 里做逐字定位也不复杂。但一旦要让文字沿任意一条平滑曲线走，就涉及“曲线上的逐字排版”这个需求。纯粹用 CSS 逐字符通过 transform 旋转位移去拼，计算量大，浏览器缩放还容易出锯齿，并不划算。

1.1 为什么首选 SVG 而不是 Canvas 和 WebGL

文本路径的核心机制在 SVG 里是现成的，也就是大家常说的 <textPath>。先有路径，再把文字挂到路径上。在这种结构里，路径只是“轨道”，文字是“列车”，列车的方向和间距会自动沿着轨道走，不需要你手动算每个字的 x、y 坐标。这意味着你在 CSS 里可以正常继承 font-family、font-size、color，浏览器也会保留文本语义，搜索引擎能读得到，文字还能被选中复制，这个优势比 Canvas 渲染文本强很多。

Canvas 虽然也有 fillText 配 measureText 实现曲线文字的能力，一切都得手写字母间距和旋转角度，代码复杂度会指数上升。WebGL 更不现实，字体解析和排版工作量太大。所以只要目标是“创意文本路径”，我的默认方案就是 SVG，让 CSS 负责外观，JavaScript 负责路径动态更新，两者各管各的，职责清楚。

1.2 JavaScript 在文本路径里到底扮演什么角色

有人会问，一个 <textPath> 标签就能搞定文本路径，为什么还要加 JavaScript？原因很直接：静态路径是写死的，但你在真实项目里遇到的可能是曲线随数据变化、文字位置随滚动移动、路径需要按鼠标拖动重算。这个时候路径 .d 属性必须被动态改写，JavaScript 就登场了。

更典型的是你不知道 target path 是什么样的。比如想让文字贴在一段波形图上，手写贝塞尔控制点纯靠蒙，大概率会歪。更好的办法是给 JavaScript 一个公式，让它根据频率、振幅、相位生成路径点坐标，再拼接成 d 字符串。这套思路在第八个片段里会展开，先有个概念就行：CSS 负责视觉层，SVG 负责结构层，JavaScript 负责数据层，三者凑齐才能做出灵活的创意文本路径效果。

2. 8 个代码片段逐个拆解

下面我会按照从易到难的顺序给出代码片段。每个片段我会保持极简，去掉多余装饰，方便你看到核心逻辑。粘贴到本地 HTML 文件里可以直接看效果，不需要任何构建工具。

2.1 片段1：第一次把文字放到一条曲线上

先建立直觉。最基础的文本路径只需要三步：定义一个 <path>，定义一个 <text>，在 <text> 内部放一个 <textPath> 指向路径。

html复制<svg viewBox="0 0 600 200" width="600" height="200">
  <defs>
    <path id="myPath" d="M 20 170 C 140 50, 300 50, 580 130" fill="none" />
  </defs>
  <text font-size="24" fill="#333" font-family="system-ui, sans-serif">
    <textPath href="#myPath">从明天起，做一个沿曲线走位的人</textPath>
  </text>
</svg>

d 里的 C 是三次贝塞尔曲线，后面两个坐标点控制的分别是曲线两端的控制点。你把 140 50 和 300 50 改大改小，曲线的弯曲方向就会跟着变。这里有个新手最容易疑惑的点：为什么路径要放在 <defs> 里？因为 <textPath> 只是“引用”路径，路径不一定非要在 <defs> 里，但放在那里更规范，避免路径本身被渲染出来。实际项目里如果路径不想显示，也不需要用 CSS 隐藏，直接把 fill="none" 写上就行。

提示：<textPath> 的文字会从路径起点开始排列。路径方向是从左到右，文字就会按照阅读方向正常横向铺开；如果你把路径方向反过来写成从右到左，文字就会自动左右翻转。

2.2 片段2：把文字精确居中对齐到路径顶点

实际设计里，很少有人需要文字从头排到尾。更多图像是一个弧线上方居中放一个短标题。此时要用一个我很常用的组合：startOffset="50%" + text-anchor="middle"。

html复制<svg viewBox="0 0 500 300" width="500" height="300">
  <defs>
    <path id="arcPath" d="M 50 240 C 100 90, 400 90, 450 240" fill="none" />
  </defs>
  <text font-size="32" fill="#c2410c" font-family="serif" text-anchor="middle">
    <textPath href="#arcPath" startOffset="50%">愿你走出半生，归来仍是少年</textPath>
  </text>
</svg>

重点解释一下 startOffset：它决定文字从路径的哪个位置开始画，可以用百分比，也可以用具体单位。设成 50%，文字就整体挪到路径中点附近。text-anchor="middle" 在这里的意思是文字锚点居中对准 startOffset 所在的那个点。没有后者的配合，仅靠 startOffset 可能只把起点中点对齐，效果就会偏。

如果你希望文字落在路径正中间，且路径很短，文字很长，那 50% 就不一定合适。文字是从中心点向两侧扩展的，中心点后面的部分如果超出路径终点，照样会被截断。要解决这个问题，建议先保证路径足够长，或者按片段4 的方式动态测量路径长度。

2.3 片段3：一条开放圆弧上的环形小标题

圆形路径经常出现在徽章、印章、Logo 文案里。很多人绕不过去的问题是：完整闭合圆会让首尾文字重叠，所以我通常先画一条开放的圆弧，而不是整个圆。比如下边这个半圆路径，视觉已经很接近“圆形文本”，又不会让接缝处难看。

html复制<svg viewBox="0 0 300 300" width="300" height="300">
  <defs>
    <path id="topArc" d="M 40 180 A 110 110 0 0 1 260 180" fill="none" />
  </defs>
  <text font-size="20" fill="#4c1d95" font-family="sans-serif" text-anchor="middle">
    <textPath href="#topArc" startOffset="50%">HALF CIRCLE TEXT EFFECT</textPath>
  </text>
</svg>

看 A 110 110 0 0 1 260 180 这段圆弧命令。A 后面前两个参数是弧的半径，这里的 110 110 表示 x 方向半径和 y 方向半径一样，也就是正圆的弧。第三个参数是旋转角度，圆弧不需要旋转就写 0。第四个参数 0 表示不取大弧，第五个参数 1 表示朝 y 轴正方向侧弯曲，最终落点是 260 180。这四个参数很容易记混，我的办法是只在数字层面微调：同样的布局，把 1 改成 0，弧就会往另一侧弯曲，文字位置也自然跑到下半侧。用这个办法可以做上下对称的双行徽章文字。

2.4 片段4：滚动页面时文字沿路径滑动的阅读条

这个效果活动页里特别常见，通栏标题的旁边配一段小字，用户滚动页面时小字慢慢沿着路径滑进去。实现思路是监听 scroll 事件，算出滚动进度，再把进度映射成 startOffset 值。

html复制<style>
  .text-path-wrap { height: 140vh; display: flex; align-items: flex-start; }
  svg { position: sticky; top: 100px; }
  .path-line { fill: none; stroke: #94a3b8; stroke-width: 1; stroke-dasharray: 4 6; }
</style>

<div class="text-path-wrap">
  <svg viewBox="0 0 800 200" width="800" height="200">
    <defs>
      <path id="scrollPath" d="M 30 100 C 180 20, 320 180, 500 90 S 720 80, 770 140" fill="none" />
    </defs>
    <path class="path-line" d="M 30 100 C 180 20, 320 180, 500 90 S 720 80, 770 140" />
    <text font-size="18" fill="#0f172a">
      <textPath href="#scrollPath" id="scrollTextPath">这段文字会随着你的滚动，顺着曲线从开头滑到结尾，像阅读器进度条一样缓缓推进。</textPath>
    </text>
  </svg>
</div>

<script>
  const textPath = document.getElementById('scrollTextPath');
  const pathLength = textPath.getComputedTextLength();

  function updateScrollText() {
    const scrollPercent = window.scrollY / (document.documentElement.scrollHeight - window.innerHeight);
    const maxOffset = textPath.getComputedTextLength();
    textPath.setAttribute('startOffset', String(scrollPercent * maxOffset));
  }

  window.addEventListener('scroll', updateScrollText);
  updateScrollText();
</script>

需要注意，代码里计算必须用 getComputedTextLength()，因为屏宽变化不会改变 SVG 内的逻辑坐标，但实际渲染字数和路径长度不一定线性相关，手动数文字的像素值不如让浏览器自己报数。另一个细节是，我给辅助路径加了一条虚线 stroke-dasharray: 4 6，目的只是让用户看到轨道在哪，如果不想要视觉效果，把样式删掉即可。

2.5 片段5：让文字沿着手写风格的曲线左右错落

设计上经常有“手写便签”“波浪描述”一类的需求。与其辛辛苦苦排多个回行，不如让 JavaScript 用正弦公式生成一条波浪路径，再把多行文字分别挂在不同相位上。

javascript复制function buildWavePath(width, height, amplitude, waveCount, phase = 0) {
  const step = 4;
  let d = '';
  for (let x = 0; x <= width; x += step) {
    const y = height / 2 + Math.sin((x / width) * Math.PI * 2 * waveCount + phase) * amplitude;
    d += (x === 0 ? 'M ' : ' L ') + x.toFixed(1) + ' ' + y.toFixed(1);
  }
  return d;
}

通过多次调用这个函数，把不同 phase 传进去，你会得到相位不同的路径。配合下边的循环创建 <textPath>，就能一次性在页面里画出多条错落的文本路径，用于做 Tag 云、诗句墙或者产品卖点列表。

实际使用时请留意波动频率。waveCount 是波形的周期数，如果设置成 10 以上，路径会变得特别弯曲，文字的字距会被拉得很开，很容易阅读困难。我的经验是创意标题波频控制在 1 到 2 个完整周期，正文类则完全不要用，会影响阅读体验。做完路径之后，编码里生成的路径其实精度已经足够，不需要再用 CSS 去修修补补。

2.6 片段6：鼠标拖拽时动态改变路径形状

交互型路径文本最大的价值是人能参与。下面这个片段让鼠标水平移动时实时改变贝塞尔曲线的高度，文字也随路径一起改变形状。实现并不复杂，只要给 SVG 路径设置新的 d，再触发一次浏览器重绘即可。

html复制<svg id="interactiveSvg" viewBox="0 0 600 250" width="600" height="250">
  <defs>
    <path id="interactivePath" d="M 50 125 Q 300 40 550 125" fill="none" />
  </defs>
  <text font-size="22" fill="#334155">
    <textPath href="#interactivePath">动动鼠标，这条路径和上面的文字都会跟着变</textPath>
  </text>
</svg>

<script>
  const svg = document.querySelector('#interactiveSvg');
  const path = document.querySelector('#interactivePath');

  svg.addEventListener('pointermove', (e) => {
    const rect = svg.getBoundingClientRect();
    const x = ((e.clientX - rect.left) / rect.width) * 600;
    const y = ((e.clientY - rect.top) / rect.height) * 250;
    const controlY = Math.min(220, Math.max(30, y));
    path.setAttribute('d', `M 50 125 Q ${x} ${controlY} 550 125`);
  });
</script>

这个例子最核心的是 Q 二次贝塞尔路径。一条二次贝塞尔由起点、一个控制点和终点构成，控制点控制整条曲线弯曲的程度和方向。当鼠标横移时只改变控制点的 y 坐标，曲线就会像拉弓形绳一样变化。如果你把 y 也拉成动态，路径就会变得不可控。此处我故意加了 Math.min 和 Math.max，因为控制点离终点太近或跑出 SVG 可视区后，文字会被截断或压得非常扁。

提示：把这个思路扩展后还可以做出“拖拽路径时逐字重新排版”的交互效果，只需要每次更新完路径后，调用一次 textPath.getComputedTextLength() 就能得到最新长度，省去手动更新的麻烦。

2.7 片段7：路径文字上加渐变和描边

文本路径在视觉上要显得“贵”，不能只用纯色。SVG 文字支持渐变填充，也支持描边，但直接设置 fill 和 stroke 时，描边默认是压在字形填充上面的。这就是很多新手明明描边很好看我却没效果的原因。正确姿势是加一个 paint-order 属性。

html复制<svg viewBox="0 0 800 240" width="800" height="240">
  <defs>
    <linearGradient id="textGrad" x1="0" y1="0" x2="1" y2="1">
      <stop offset="0%" stop-color="#f59e0b"/>
      <stop offset="50%" stop-color="#ef4444"/>
      <stop offset="100%" stop-color="#8b5cf6"/>
    </linearGradient>
    <path id="gradPath" d="M 20 200 C 150 40, 500 40, 780 160" fill="none" />
  </defs>
  <text font-size="36" fill="url(#textGrad)" stroke="#111827" stroke-width="2" paint-order="stroke fill"
        font-family="sans-serif" font-weight="700">
    <textPath href="#gradPath">渐变与描边叠加的路径大字</textPath>
  </text>
</svg>

paint-order="stroke fill" 表示让描边先画，填充后画，这样填充会覆盖描边的内侧，文字看起来就有一圈均匀的描边。反过来的默认绘制顺序里，粗描边会把字的里侧吃掉一半，细笔画多的时候甚至会糊成一团。这个属性在普通文本上也能用，但在路径文本上更重要，因为路径的弧度会导致笔画的粗细投影差异更大。做活动主视觉标题时，这套组合基本能给你直接可用的设计稿质感。

2.8 片段8：动态生成多条路径，让文字排成波浪矩阵

这个片段可以看成前几个片段的综合升级版：用 JavaScript 循环生成多条波形路径，每个路径都挂一行文字，最后形成“文字波浪”。用在个人 Profile 页面、产品介绍、音乐播放页的歌词墙都很有代入感。

html复制<div id="waveTextContainer"></div>

<script>
  const container = document.getElementById('waveTextContainer');
  const width = 800;
  const height = 320;
  const rows = 4;
  const lines = [
    '第一行文字像浪尖',
    '第二行文字贴着波谷',
    '第三行可以错开相位',
    '第四行收在画面底部'
  ];

  let ns = 'http://www.w3.org/2000/svg';
  let svg = document.createElementNS(ns, 'svg');
  svg.setAttribute('viewBox', `0 0 ${width} ${height}`);
  svg.setAttribute('width', '100%');

  for (let i = 0; i < rows; i++) {
    const pathId = 'wavePath' + i;
    const pathEl = document.createElementNS(ns, 'path');
    pathEl.id = pathId;
    pathEl.setAttribute('d', makeWave(width, 30 + i * 65, 16, 2, i * 1.2));
    svg.appendChild(pathEl);

    const textEl = document.createElementNS(ns, 'text');
    textEl.setAttribute('font-size', '15');
    textEl.setAttribute('fill', '#334155');
    const tp = document.createElementNS(ns, 'textPath');
    tp.setAttribute('href', '#' + pathId);
    tp.textContent = lines[i];
    textEl.appendChild(tp);
    svg.appendChild(textEl);
  }

  function makeWave(w, baselineY, amplitude, periodic, phase) {
    let d = '';
    for (let x = 0; x <= w; x += 6) {
      const y = baselineY + Math.sin((x / w) * Math.PI * 2 * periodic + phase) * amplitude;
      d += (x === 0 ? 'M ' : ' L ') + x.toFixed(1) + ' ' + y.toFixed(1);
    }
    return d;
  }

  container.appendChild(svg);
</script>

用 createElementNS 创建 SVG 元素是本片段关键。一定不要用 createElement，否则浏览器会把元素当成普通的 HTML unknown element，渲染不出来。路径方向这里也要注意，路径必须从左到右生成，文字才不会被镜像反转。如果文字放在路径右侧却想左对齐阅读，也可以在不同路径上用 direction: rtl 配合生成从右到左的路径，这个方式我会在下一个部分详细对比。

3. 路径参数到底怎么调，才能让文本符合直觉

面对一堆路径坐标，新手最头疼的是不清楚每个数字影响什么。文本路径本质上是一个“排版轨道”，所以与其背 SVG 命令，不如掌握几个直接影响文本布局的参数。

3.1 读懂 path 的 d 字符串，知道你的轨道长什么样

文本路径绝对多数是 M、L、Q、C、A 这几种命令的组合。M 是落笔点，L 是直线，弯曲线主要是 Q（二次贝塞尔）和 C（三次贝塞尔）。

我建议日常做文本轨道时多用 Q，因为它只有一个控制点，直觉上最接近“我往这个方向拉了一下”。三是把轨道设计成先陡后缓的形状时，用 C 更能细分，但调试成本高。实际项目中，如果曲线需要匹配某个插画素材，我更偏向用设计软件导出 SVG path，而不是自己手写。这里需要特别提醒：从 Figma、Sketch 导出的路径常常会有很多冗余节点，只要生成的曲线不过度抖动，文本还是能正常排。而过度抖动的路径会让文字忽上忽下，视觉噪声极大。

3.2 startOffset、text-anchor、lengthAdjust 的分工

这三个属性决定文字在轨道上的“锚点位置”“对齐规则”和“是否拉伸”。如果你有三个不同需求，最好按以下原则配置：

lengthAdjust 是个容易被忽略的文本路径高级参数。默认值是 spacing，文字不够的时候只会拉大字符间距，而 spacingAndGlyphs 会连字本身的宽度一起缩放。创意海报里，如果想强行把一句话铺满整条曲线，可以设置一个足够大的 textLength，同时配 lengthAdjust="spacingAndGlyphs"。这样做出来的字会被拉伸，尽量少用于正文，但作为装饰性英文标题很有张力。

3.3 路径方向和文字可读性

这个问题排在最常见的坑前三名。SVG 的路径方向会影响文字的正反朝向。规则可以这样理解：文字始终“走在”路径前进方向的右侧，字顶朝路径内侧。如果你发现文字上下颠倒，最直接的办法不是翻转 transform，而是把路径方向反过来。

判断路径方向最笨也最有效的方式是给路径加一个 marker-end，放一个小箭头。箭头在哪，路径的终点就在哪。反向路径通常只要把路径坐标反过来写一遍，例如原先是 M 30 100 Q 300 30 570 100，反向就是 M 570 100 Q 300 30 30 100。两个控制点互换后，曲线的几何形状完全没变，但方向反了，文字也随之反向可读。如果你用的是圆弧命令里的 sweep-flag，直接改 0 变 1 也行。

4. 上线前最容易踩的 5 个坑

文本路径效果看起来炫，一旦上线到真实页面，各种尺寸和内容问题就出现了。我从项目里踩过并修复过的问题里，挑了高频且隐蔽的 5 个，列成一张速查表。

4.1 文字截断问题的应急处理

一旦出现文字被截断，最有效的调试方法是给 path 增加一个临时可见的虚线描边，比如 stroke="#333" stroke-dasharray="4 4"。这样能直接看出文字在哪个位置越过了路径终点。然后优先检查是路径太短还是路径方向不对。如果路径长度实在受限，可以考虑将文字拆成两组，分别挂到两条路径上。拆组的时候两条路径尽量保持一个圆滑拐角，视觉上才不会像换行生硬。

我经常用的另一个办法是在文本结尾加一个尽可能长的空格，借助 getComputedTextLength() 提前算一下整段文字的宽度，再去调整 viewBox 或者路径。新手可能不知道，<textPath> 文字测量是支持空格宽度的，先把内容写成单个字符串测一遍，比肉眼慢慢试错节约大量时间。

4.2 字体缺失导致的诡异间距问题

路径文本跟普通文本一样，也会受字体回退影响。如果你的 CSS 里定义了某种非系统字体，而用户电脑没有这个字体，浏览器会回退到默认字体，字宽就不一致了，路径相同文字也会重新排布，看起来像是路径错位。做文本路径动效时，最稳妥的做法是优先使用本地字体，或者把字体真正通过 @font-face 加载，不要依赖系统字体回退链。

如果你给文本加上了字距 letter-spacing，也一定先确认是给 <text> 设置还是给包裹它的普通元素设置。SVG 内部的字距继承规则和 HTML 略有差异，直接写在 <text> 或 <textPath> 上才靠谱。把它写到外层 <div> 上经常会失效，这也是很多人以为代码有 bug 的原因。

4.3 响应式缩放后手势坐标换算

第 6 个片段里用到了指针坐标到 SVG 坐标的换算。我最初做的版本直接用了 clientX，没有考虑 SVG 的局部坐标，结果拖拽路径时文字总是偏离鼠标一大截。所有 SVG 交互都要做一次坐标换算：先把屏幕坐标减去 getBoundingClientRect 的 top 和 left，再按 viewBox 宽度和实际渲染宽度的比例进行缩放。不同断点里，如果外层宽度变化了，这个换算必须重新执行一次，否则移动端和桌面端表现完全不同。

好在这类成本不高，在第 6 个片段的代码里我已经把换算写进去了，直接复用即可。如果你的 SVG 内部还有嵌套结构，还要小心 getScreenCTM() 的矩阵乘算，不过文本路径场景一般不涉及那么深的嵌套，简单换算就够用。

5. 一些我认为值得记住的通用建议

项目里真正让文本路径从“能用”变“好用”，很多时候不是技术多花哨，而是排版细节到位。下面三条建议是我做完多个创意页面后沉淀下来的，纯个人经验，没有任何教科书负担。

第一，文字内容是动态的，一定要预留路径余量。比如接口返回的文案比设计稿预期多了十个字，路径瞬间就崩了。最省事的做法是写一个工具函数：入参是文字内容和一个基础路径 d，函数内部把路径长度通过 getTotalLength() 算出来，跟文字的 getComputedTextLength() 做对比，不够长就自动延长路径终点。这个逻辑不复杂，但能救很多临场的展示事故。

第二，动画不要忘了 will-change。如果做滚动跟随或者拖拽更新路径，SVG 里的文字会频繁触发重排，老电脑卡到怀疑人生。在 textPath 或 SVG 外层加 will-change: contents 或适当触发 GPU 合成，能改善一些掉帧感。当然，路径重绘本身主要消耗 CPU，真正流畅的交互还是需要减少每帧更新的路径节点数量，能用 20 个路径点表达曲线，就不要生成 200 个。

第三，强调路径文本的可访问性。用 SVG <text> 有一个隐性优势：屏幕阅读器通常能识别文字内容，但如果你用纯 Canvas 画曲线文本，屏幕阅读器的状态就是黑的。如果你为了兼容低版本浏览器不得不用图片替代，那么至少补一个 alt 或者隐藏的 HTML 同文。这一点常常被忽略，但产品上线前被无障碍扫描工具报出来还是挺麻烦的。

做文字路径本身并没有高深到需要啃完整本 SVG 规范，关键是理解清楚“文字是沿着路径这根轨道找位置的”这一思维模型。轨道写得好不好，直接影响文字可读性和视觉美感。从最基础的 <textPath>，到动态修改 startOffset，再到用 JavaScript 按公式生成波浪路径，你会发现这 8 个代码片段其实是在帮你搭一套“从静态到交互”的思考脚手架。遇到具体项目时，先确认需求是单纯视觉装饰还是需要用户交互，再决定用哪个片段打底即可。后面如果你有更特殊的路径形态需求，比如文字绕着不规则多边形走，本质上也只是换一种路径生成函数，其他渲染逻辑不需要变动。