通过HTTP PUT发送JSON保留格式——Azure DevOps Wiki自动更新问题

需求可行性 #

完全可行，问题根源在于手动拼接JSON时的转义处理错误，而非API本身不支持保留Mermaid格式。

核心问题分析 #

你当前的脚本用printf %q处理内容，会生成Shell转义格式的字符串，而非JSON要求的转义规则：

• 换行符会被转成Shell专用的转义格式，无法被JSON解析器正确识别
• 双引号、反斜杠等特殊字符未按JSON规则转义，导致API解析失败或内容变形为单行文本

正确脚本实现 #

使用jq工具（Azure DevOps流水线代理默认已预装，若缺失可通过任务快速安装）自动处理JSON转义，彻底避免手动拼接的错误：

# 读取Mermaid文件完整内容（保留所有换行和格式）
val=$(cat diagrams/structurizr-Diagram1.mmd)

# 用jq生成符合JSON规范的请求体，自动处理所有特殊字符转义
json=$(jq -n --arg content "$val" '{"content": $content}')

# 发送API更新请求
responseCreate=$(curl -X PUT \
  -H "Content-Type: application/json" \
  -d "$json" \
  "https://feedname:$(WIKI_TOKEN)@dev.azure.com/[组织名]/[项目名]/_apis/wiki/wikis/[Wiki标识]/pages?path=[目标页面路径]&api-version=7.1-preview.1")

关键说明 #

• jq会自动处理所有JSON特殊字符（双引号、反斜杠、换行、制表符等），确保Mermaid图的格式100%保留
• 替换URL中的[组织名]、[项目名]、[Wiki标识]、[目标页面路径]为实际值
• 若流水线代理未安装jq，可添加前置Bash任务：Ubuntu代理执行sudo apt-get install -y jq，Windows代理执行choco install jq -y

替代方案 #

方案1：渲染为图片上传 #

1. 用Mermaid CLI将.mmd文件渲染为PNG/SVG：

   npx @mermaid-js/mermaid-cli -i diagrams/structurizr-Diagram1.mmd -o diagrams/architecture.png
   

2. 通过Azure DevOps API将图片上传至Wiki附件库，然后在页面中插入图片引用：

   ![系统架构图](/.attachments/architecture.png)
   

方案2：上传源文件并插入链接 #

1. 将.mmd源文件上传至Wiki附件库
2. 在Wiki页面中添加源文件链接：

   [查看架构图源文件](/.attachments/structurizr-Diagram1.mmd)
   

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