如何避免Markdown图片URL模板变量被编码？（marked/CommonMark）

一、CommonMark/GFM规范层面 #

CommonMark和GFM规范本身要求对URL中的特殊字符（包括花括号{}）进行URL编码，这是符合标准URL规则的，所以仅靠规范本身无法避免这个问题，必须通过渲染器的自定义配置来实现需求。

二、marked库的具体解决方案 #

marked库支持自定义渲染逻辑，我们可以通过重写图片渲染函数来保留模板变量的原始格式：

方法1：自定义图片渲染器 #

直接覆盖默认的image渲染方法，手动拼接HTML代码，跳过marked默认的URL编码步骤：

const marked = require('marked');

// 初始化自定义渲染器
const customRenderer = new marked.Renderer();
customRenderer.image = function(href, title, text) {
  // 转义alt和title中的双引号，避免HTML语法错误
  const escapedAlt = text.replace(/"/g, '"');
  const escapedTitle = title ? ` title="${title.replace(/"/g, '"')}"` : '';
  // 直接使用原始href，不编码
  return `<img src="${href}" alt="${escapedAlt}"${escapedTitle} />`;
};

// 使用自定义渲染器解析Markdown
const markdownContent = '![alt-text]({urlVar})';
const htmlResult = marked(markdownContent, { renderer: customRenderer });
console.log(htmlResult);
// 输出：<img src="{urlVar}" alt="alt-text" />

方法2：使用marked的扩展语法配置 #

也可以通过marked.use()方法注入自定义渲染规则，写法更简洁：

const marked = require('marked');

marked.use({
  renderer: {
    image(href, title, text) {
      const escapedAlt = text.replace(/"/g, '"');
      const titleAttr = title ? ` title="${title.replace(/"/g, '"')}"` : '';
      return `<img src="${href}" alt="${escapedAlt}"${titleAttr} />`;
    }
  }
});

const output = marked('![alt-text]({urlVar})');
console.log(output);

注意事项 #

• 自定义渲染时要注意XSS风险：如果后续注入的{urlVar}包含用户输入内容，需要在模板引擎处理完成后，对最终HTML进行安全校验或 sanitize 处理。
• 不要全局禁用marked的URL编码功能，仅针对需要保留模板变量的元素（比如图片链接）单独处理，避免破坏其他合法URL的编码逻辑。

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