GitLab CI/CD中Confluence Publisher报错：页面标题已存在

问题现象 #

• 首次通过GitLab CI/CD使用confluence-publisher Docker镜像发布AsciiDoc文档到Confluence，成功创建目标页面
• 后续生成新版本再次发布时，触发错误：

  A page with this title already exists: A page already exists with the same TITLE in this space

• 当前Confluence空间内仅存在待编辑的目标页面，无重复标题页面
• 仅保留祖先页面并修改其名称后，流水线可正常运行

原因分析 #

这个问题核心是confluence-publisher在匹配待更新页面时，依赖页面的完整祖先路径做唯一性校验，而非仅目标页面标题。哪怕目标页面本身唯一，但如果之前发布时的祖先路径和当前配置的路径存在差异（比如父页面名称变更、层级调整），工具会误将本次发布判定为创建新页面，却发现目标标题已存在，从而抛出冲突错误。

解决方案 #

1. 锁定页面祖先路径一致性：确保每次发布时，AsciiDoc文档中定义的页面父层级路径，和Confluence中实际的页面路径完全匹配，避免路径名称或层级的变动
2. 清理历史页面关联痕迹：检查Confluence的页面版本历史、回收站，确认是否存在之前发布遗留的同标题/关联页面数据，彻底清理后重新发布
3. 强制以页面ID匹配更新：在confluence-publisher的配置中，直接指定目标页面的Confluence ID（可从页面URL中提取），让工具以ID作为匹配依据，绕过标题+路径的校验逻辑

临时验证有效的 workaround #

如你已经尝试的，临时保留祖先页面并修改其名称，让发布路径与工具预期的路径匹配，可快速解决当前发布阻塞问题，但长期建议采用上述方案从根源避免此类问题。

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