因为gin.StaticFS未设置Content-Disposition: inline响应头，浏览器默认强制下载而非内嵌预览；Office文件需转PDF或用Collabora等第三方服务，不可原生预览。
为什么直接用 gin.StaticFS 无法预览 Office 或 PDF 文件？
因为 gin.StaticFS 默认只设置 Content-Type 为文件扩展名对应类型（如 application/pdf），但浏览器是否能内嵌预览，取决于响应头中是否包含 Content-Disposition: inline。缺这个头，Chrome/Firefox 就会强制下载而不是打开。
常见错误现象：GET /docs/report.pdf 返回 200，但浏览器弹下载框；检查响应头发现没有 Content-Disposition 或值为 attachment。
- PDF、TXT、SVG、PNG、JPEG 等支持 inline 渲染的格式，需显式加
Content-Disposition: inline - Office 文件（
.docx,.xlsx）本身不被浏览器原生支持，必须转成 PDF 或用第三方服务（如 OnlyOffice、Collabora），Gin 层只能做透传或跳转 - 别硬改
gin.StaticFS源码——它不提供 header 注入钩子，强行 patch 容易在升级后失效
如何用 gin.File + 手动设置 header 实现安全预览
gin.File 比 StaticFS 更可控：它允许你在发送前修改 header，且支持路径校验（避免目录遍历）。适合单个已知路径的文件预览。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 对每个请求路径做白名单校验，比如只允许
/preview/*下的.pdf、.txt、.svg - 用
mime.TypeByExtension获取正确Content-Type，别硬编码 - 统一加
c.Header("Content-Disposition", "inline")，不要漏掉 - 务必调用
c.Writer.WriteHeader(200)再调c.File(...)，否则 header 可能被覆盖
c.Header("Content-Disposition", "inline")
c.Header("Content-Type", mime.TypeByExtension(filepath.Ext(path)))
c.Writer.WriteHeader(200)
c.File(path)
怎么让 .docx 也能“看起来像预览”？
浏览器不能直接渲染 .docx，所以所谓“预览”本质是跳转或代理。最轻量方案是生成临时 PDF 并重定向，或用 LibreOffice CLI 转换（需服务器装 LibreOffice）。
注意点：
- 别在 HTTP handler 里同步调用
libreoffice --convert-to pdf—— 耗时长、易超时、阻塞 goroutine - 推荐做法：收到请求后，返回 302 到一个带 token 的临时 URL（如
/temp/abc123.pdf），后台异步转换并缓存，过期自动清理 - 如果不想引入 LibreOffice，可跳转到 Docs Online（如
https://view.officeapps.live.com/op/view.aspx?src=xxx），但要注意源文件必须公网可访问且无认证 - 绝对禁止把用户上传的
.docx直接丢给第三方在线查看服务——存在隐私泄露风险
路径校验和 MIME 类型陷阱
用户可能构造恶意路径（如 ../../../etc/passwd）或伪造扩展名（如 shell.php.pdf），导致文件读取越界或执行风险。
关键处理：
- 用
filepath.Clean()规范路径，再检查是否以白名单根目录开头（如strings.HasPrefix(cleaned, "/var/www/docs/")） - 不要只靠扩展名判断类型——攻击者可改后缀。用
net/http.DetectContentType读前几个字节做二次校验 - PDF 文件开头应为
%PDF-，TXT 应为 ASCII 可读字符，图片应有对应 magic bytes。不匹配就c.AbortWithStatus(400) - 对
.html、.js等可执行类型，即使想“预览”，也应拒绝 inline，强制Content-Disposition: attachment
复杂点不在代码行数，而在校验链是否闭环：路径 → 扩展名 → 字节签名 → MIME → header 策略，漏一环就可能变成文件服务器漏洞。
