Buffalo 文件下载需绕过模板渲染，手动设置 Content-Disposition 和 Content-Type 头，禁用 Render()，使用 Response().Write() 或 io.Copy；API 模式下应裸挂 http.Handler 避免中间件干扰，大文件需 Flush、自定义 buffer 并禁用日志；Content-Length 须 Header.Set 而非 WriteHeader，推荐 http.ServeContent。
Buffalo 路由返回文件下载响应要绕过模板渲染
Buffalo 默认所有 c.Render() 都走 HTML 模板流程，直接调用会导致 500 错误或空响应。文件下载必须跳过模板系统，手动设置 header 并写入 body。
常见错误现象：template "xxx.html" does not exist、浏览器弹出空白页、响应体为空但状态码是 200。
- 用
c.Response().Header().Set("Content-Disposition", "attachment; filename=xxx.zip")显式声明下载行为 - 必须调用
c.Response().Header().Set("Content-Type", "application/octet-stream")，不要依赖 MIME 自动推断 - 禁止调用任何
c.Render()，改用c.Response().Write()或io.Copy(c.Response(), file) - 确保文件路径安全：避免用户输入拼接路径，用
filepath.Join()+filepath.Clean()校验
buffalo new --api 项目里怎么注册下载路由
API 模式下默认不加载模板中间件，但 app.GET() 注册的 handler 仍可能被全局中间件干扰（比如自动 JSON 封装）。下载接口必须“裸露”在最外层。
推荐做法是单独挂一个不经过 Buffalo 中间件链的 handler：
- 在
app.go的app.Use()之前，用http.Handle("/download/xxx", http.HandlerFunc(downloadHandler)) - 或者用
app.Mount("/download", http.StripPrefix("/download", http.FileServer(http.Dir("./files"))))快速暴露静态目录（仅限可信内部路径） - 若需鉴权，把鉴权逻辑写进
downloadHandler函数内，别依赖middleware.Authorize—— 它默认只对buffalo.Context生效，而裸http.HandlerFunc没有该类型
大文件下载容易触发超时或内存溢出
Buffalo 的 Context 默认启用 request body 缓存和日志中间件，对大文件响应会吃光内存或卡死连接。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 务必在下载 handler 开头加
c.Response().Flush()，避免缓冲区堆积 - 用
io.CopyBuffer()替代io.Copy()，自定义 32KB 以上 buffer 提升吞吐 - 禁用日志中间件对该路径：在
app.Use()前插入条件判断，对/download/*跳过middleware.Logger - 检查
buffalo dev启动时是否带--log-level=warn，开发期避免每字节都打日志
为什么 Content-Length 经常不生效
Buffalo 的 ResponseWriter 包装层会拦截 WriteHeader() 调用，导致手动设 Content-Length 失效，浏览器无法显示进度条。
根本原因是 Buffalo 在 context.go 里重写了 WriteHeader，且未透传原始 http.ResponseWriter 的 WriteHeader 行为。
- 绕过方式：用
c.Response().Header().Set("Content-Length", strconv.FormatInt(fileSize, 10))，然后直接c.Response().Write()—— 不要调用c.Status() - 更稳妥的做法：用
http.ServeContent()，它会自动处理Range请求和Content-Length，但要求你提供http.FileInfo实现 - 注意：Buffalo 的
buffalo.Context没暴露底层http.ResponseWriter的Hijack或Flush接口，所以别试图强转类型
真正麻烦的是当下载路径需要动态生成、又得走鉴权+审计日志时，Buffalo 的中间件模型很难干净拆分——要么自己实现一个轻量 http.Handler 嵌套进 Buffalo 生命周期，要么干脆用原生 net/http 单独起个下载子服务。后者在生产环境反而更可控。
