Flutter Markdown如何加载SVG/PNG/JPG图片及解决网络图片404报错

• flutter_markdown默认内置的图片渲染逻辑仅支持PNG、JPG等位图格式，遇到SVG资源会直接调用系统NetworkImage加载，无法正确解码SVG格式导致渲染异常
• 现有代码重复向inline语法列表注入md.ImageSyntax，会导致「链接嵌套图片」的徽章类Markdown语法解析出错，无法正确提取图片地址
• 直接请求GitHub静态资源时未携带合法请求头，会被平台拦截返回404
• 代码中注释掉了imageBuilder自定义渲染入口，没有做不同图片格式的分发处理逻辑

1. 修正语法集配置 #

移除重复注入的md.ImageSyntax，该语法已经包含在GitHub Flavored默认语法集中，重复添加会导致解析冲突：

extensionSet: md.ExtensionSet(
  md.ExtensionSet.gitHubFlavored.blockSyntaxes,
  [
    md.EmojiSyntax(),
    ...md.ExtensionSet.gitHubFlavored.inlineSyntaxes,
  ],
),

2. 实现自定义图片构建器 #

通过imageBuilder参数拦截所有Markdown中的图片节点，按照格式分发到对应的渲染组件，同时补充合法请求头避免平台拦截：

Markdown(
  controller: controller,
  selectable: true,
  data: aboutMD,
  // 自定义图片渲染逻辑
  imageBuilder: (uri, title, alt) {
    final imgPath = uri.toString();
    // 识别SVG格式资源
    if (imgPath.toLowerCase().endsWith('.svg')) {
      return SvgPicture.network(
        imgPath,
        // 携带合法UA，避免GitHub等平台返回404
        headers: const {
          'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36'
        },
        semanticsLabel: alt ?? title ?? '',
        // 加载占位
        placeholderBuilder: (context) => const SizedBox(
          width: 80,
          height: 20,
          child: Padding(
            padding: EdgeInsets.all(2.0),
            child: LinearProgressIndicator(strokeWidth: 1),
          ),
        ),
      );
    }
    // 渲染PNG、JPG等位图格式
    return Image.network(
      imgPath,
      headers: const {
        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36'
      },
      errorBuilder: (context, error, stackTrace) => Text(
        alt ?? '图片加载失败',
        style: const TextStyle(fontSize: 12, color: Colors.grey),
      ),
      semanticLabel: alt ?? title ?? '',
    );
  },
  extensionSet: md.ExtensionSet(
    md.ExtensionSet.gitHubFlavored.blockSyntaxes,
    [
      md.EmojiSyntax(),
      ...md.ExtensionSet.gitHubFlavored.inlineSyntaxes,
    ],
  ),
)

如果需要支持本地Asset图片、本地文件图片，可以在imageBuilder中通过uri.scheme判断来源：

• scheme为asset时，调用Image.asset(uri.path)渲染
• scheme为file时，调用Image.file(File(uri.path))渲染
• 其余逻辑和网络图片一致，根据后缀判断是否为SVG做对应分发即可

带跳转链接的图片（如GitHub构建徽章）不需要额外处理，flutter_markdown默认支持点击图片触发外层链接跳转。

内容的提问来源于stack exchange，提问作者Aung Ye Zaw