如何开发Gatsby插件为MDX匹配规则的外链添加URL参数？

核心实现思路 #

• 解析MDX内容：借助@mdx-js/mdx这类工具解析MDX的AST（抽象语法树），遍历节点分别处理两种链接类型：
  • Markdown原生链接：定位link类型节点，提取URL后匹配指定域名，符合规则就追加参数
  • JSX <a>标签：识别包含<a的JSX节点，提取href属性值，执行相同的域名匹配与参数追加逻辑
• 参数处理要严谨：别手动拼接URL参数，用浏览器原生URL对象处理最稳妥——不管原URL有没有参数，searchParams.set()都会自动处理?和&的问题，避免格式错误
• 集成到构建流程：根据你使用的构建工具（Vite、Webpack等）编写对应插件，在构建的transform阶段拦截MDX文件，修改完成后再输出处理后的内容

Vite插件简单示例 #

import { visit } from 'unist-util-visit';
import { compile } from '@mdx-js/mdx';

export default function mdxLinkTrackingPlugin({ pattern, trackingId }) {
  return {
    name: 'mdx-link-tracking',
    async transform(code, id) {
      if (!id.endsWith('.mdx')) return code;

      // 解析MDX为AST结构
      const ast = await compile(code, { outputFormat: 'ast' });
      // 遍历处理所有链接节点
      visit(ast, (node) => {
        // 处理Markdown链接
        if (node.type === 'link') {
          try {
            const url = new URL(node.url);
            if (url.hostname.includes(pattern)) {
              url.searchParams.set('trackingId', trackingId);
              node.url = url.toString();
            }
          } catch {}
        }
        // 处理JSX a标签
        if (node.type === 'jsx' && node.value.includes('<a')) {
          node.value = node.value.replace(/href="([^"]+)"/g, (match, href) => {
            try {
              const url = new URL(href);
              if (url.hostname.includes(pattern)) {
                url.searchParams.set('trackingId', trackingId);
                return `href="${url.toString()}"`;
              }
            } catch {}
            return match;
          });
        }
      });

      // 将修改后的AST转回MDX代码
      const result = await compile(ast, { outputFormat: 'mdx' });
      return result.value;
    }
  };
}

注意事项 #

• 确保MDX解析器与构建工具版本兼容，不同版本的AST结构可能存在差异
• 相对链接、无效URL或非目标域名的链接要直接跳过，避免误修改
• 若遇到href={someVariable}这类动态JSX值，静态处理无法覆盖，需结合构建时变量注入或额外静态分析逻辑解决

内容的提问来源于stack exchange，提问作者Florian