文档Experience Cloud KCS

AEM Guides：当xref在链接中使用mailto：#时，站点生成失败

最近更新： 2026年6月25日

当xref包含以#字符开头的mailto链接时，本文介绍了如何在Adobe Experience Manager Guides中生成站点。

描述 description

环境

Adobe Experience Manager Guides（所有版本）
问题/症状

使用预设生成AEM Sites输出时，如果xref元素包含以#字符开头的mailto链接（例如： mailto:#example@example.com），则流程会失败。

在站点生成期间出现以下错误：

BUILD FAILED
/mnt/crx/author/crx-quickstart/profiles/ditaot--<profile-id>/DITA-OT/plugins/org.dita.base/build_preprocess.xml:62:
Failed to run pipeline: Expected scheme-specific part at index 7: mailto:#example@example.com
  • 通过在任何主题中添加带mailto:#的xref并尝试生成AEM Sites输出，该问题可重现。
  • 在DITA-OT预处理步骤中出错。

有关其他上下文，请参阅基于DITA URI的寻址文档：

解决方法 resolution

  1. 更新xref元素以对#字符使用百分比编码。
    不要使用< xref> mailto:#example@example.com​< /xref>将#编码为%23。

    例如：

    code language-none 
    <xref href="mailto:%23example@example.com" format="html">Contact Support</xref>

​2. Ensure the xref uses the href attribute and includes display text.

  • This helps DITA-OT correctly interpret the link as an external reference.
    ​3. Save the topic and regenerate the AEM Sites output using Presets.
  • The site generation should now complete successfully without errors.

Cause

The DITA-OT processor interprets the # character as a fragment identifier within URIs. When used directly in a mailto link, it causes URI parsing errors. Percent-encoding the # character as %23 allows DITA-OT to process the link as intended.

recommendation-more-help
experience-cloud-kcs-help-kbarticles