MSYS2/Linux跨平台Doxygen INPUT_FILTER路径斜杠兼容问题

问题根因 #

Doxygen 1.9.3版本在MSYS2/Windows环境下通过popen调用输入过滤器时，不会自动转换正斜杠分隔的相对路径，会直接将字符串传给系统执行，和MSYS2的路径自动转译逻辑冲突，导致无法定位到res目录下的过滤器脚本；而Linux环境不识别反斜杠作为路径分隔符，直接写死反斜杠路径会在Linux下失效。

可落地兼容方案（按推荐优先级排序） #

• 方案1：启动脚本动态注入平台适配的绝对路径（最稳定）
  不要在模板配置文件里写死过滤器的相对路径，改由顶层bash启动脚本根据当前运行环境动态生成适配路径，替换模板占位符后再启动Doxygen：

  1. 把res/template.doxyfile里的过滤器配置行替换为占位符：

     INPUT_FILTER           = @INPUT_FILTER_PATH@
     

  2. 在顶层启动脚本中添加环境判断、路径转换逻辑，示例代码：

     #!/bin/bash
     # 获取脚本所在项目根目录的绝对路径
     PROJECT_ROOT=$(cd "$(dirname "$0")" && pwd)
     FILTER_RAW_PATH="$PROJECT_ROOT/res/doxyfilter.py"
     
     # 识别MSYS2环境，转换为Windows原生路径格式
     if [[ "$OSTYPE" == "msys" ]]; then
         FILTER_FINAL_PATH=$(cygpath -w "$FILTER_RAW_PATH")
     else
         FILTER_FINAL_PATH="$FILTER_RAW_PATH"
     fi
     
     # 替换模板占位符生成临时运行配置
     sed "s|@INPUT_FILTER_PATH@|$FILTER_FINAL_PATH|g" "$PROJECT_ROOT/res/template.doxyfile" > /tmp/doxy_run_config
     # 启动Doxygen
     doxygen /tmp/doxy_run_config
     # 清理临时文件
     rm -f /tmp/doxy_run_config
     

  该方案全程使用绝对路径调用，完全避开相对路径解析、分隔符不兼容的问题，双平台下都不会出现路径找不到的错误。

• 方案2：显式指定Python解释器调用过滤器（改动最小）
  如果不想改动启动脚本逻辑，可以直接把Doxygen配置里的过滤器路径改为显式调用Python解释器的形式：

  INPUT_FILTER           = python res/doxyfilter.py
  

  这种写法下Doxygen会直接调用系统PATH中的Python解释器，再把脚本路径作为参数传给Python，MSYS2和Linux环境下的Python都原生支持正斜杠分隔的路径，不会触发Doxygen本身的路径解析bug。只需要保证双平台下Python命令可全局调用即可。

避坑说明 #

不要尝试在配置中混用正反斜杠，也不要依赖Doxygen自带的路径自动转换能力，1.9.3版本Windows环境下的popen路径处理存在已知缺陷，传入经平台适配的绝对路径是容错率最高的实现方式。

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