Flask+Botbuilder开发Azure机器人HeroCard本地图片不更新问题

• 通道侧多层缓存：Azure Bot对接的各类客户端（Web Chat、Teams、Slack等）、中间CDN节点默认会对卡片引用的图片资源做强缓存，缓存键为图片的完整URL。只要URL不变，即使源站的图片被修改、删除，缓存层会直接返回已存储的旧版本资源，不会回源到你的Flask服务拉取新文件，这是该问题的核心诱因。
• Flask静态资源默认缓存规则：Flask默认的static路由会自动给静态资源添加带长效过期时间的Cache-Control响应头，请求方拿到响应头后会按规则在有效期内直接使用本地缓存，不会主动校验源站文件是否更新。
• 客户端本地缓存：测试过程中使用的对话客户端会缓存已经加载过的图片资源，即使后端资源更新，未清理缓存的客户端仍会展示本地存储的旧图片。

• 强制URL版本化破缓存（优先推荐，适配所有缓存层）
  每次构造HeroCard的图片地址时，不要使用固定的静态路径，在URL后拼接随图片内容变化的查询参数（比如文件最后修改时间戳、图片内容哈希），参数变化后对所有缓存层来说都是全新的资源地址，会自动回源拉取最新文件。
  参考实现代码：

  import os
  from botbuilder.schema import HeroCard, CardImage
  
  # 本地动态图片存放路径
  dynamic_img_abs_path = os.path.join(app.static_folder, "cards", "user_target.png")
  # 取文件最后修改时间作为版本号，文件内容修改时时间戳会自动变化
  img_ver = int(os.path.getmtime(dynamic_img_abs_path))
  # 拼接带版本参数的公网可访问图片地址
  img_public_url = f"{request.host_url}static/cards/user_target.png?v={img_ver}"
  
  # 构造HeroCard
  card = HeroCard(
      title="业务动态卡片",
      images=[CardImage(url=img_public_url)]
  )
  

• 调整动态图片路径的缓存响应头
  对存放动态卡片图片的路由路径，单独配置响应头禁用缓存，强制请求方每次都回源校验资源版本。
  参考实现代码：

  @app.after_request
  def disable_dynamic_img_cache(response):
      # 匹配动态卡片图片的请求路径
      if request.path.startswith("/static/cards/dynamic/"):
          response.headers["Cache-Control"] = "no-cache, no-store, must-revalidate"
          response.headers["Pragma"] = "no-cache"
          response.headers["Expires"] = "0"
      return response
  

  注意：该方案仅能控制Flask源站返回的缓存规则，无法干预Azure Bot通道侧的CDN缓存，实际生效效果弱于URL版本化方案。
• 动态图片实时流式返回
  对于高频变更的动态图片，可以不存为本地静态文件，而是在生成图片内容后通过专用接口直接返回PNG二进制流，从根源规避静态资源默认缓存逻辑。
  参考实现代码：

  from flask import send_file
  from io import BytesIO
  
  @app.route("/api/card-img/<user_id>")
  def dynamic_card_img(user_id):
      # 这里写根据用户ID生成对应PNG二进制内容的业务逻辑
      png_content_bytes = generate_user_specific_png(user_id)
      return send_file(
          BytesIO(png_content_bytes),
          mimetype="image/png"
      )
  

  构造HeroCard时将图片地址指向该接口即可，同样建议拼接时间戳参数避免缓存。

验证提示：如果调整后仍看到旧图，可新开对话会话、清空客户端缓存后再测试，排除本地历史缓存的干扰。

内容的提问来源于stack exchange，提问作者Hoang Cao Bao