文件下载安全（Content-Disposition与类型校验）最佳实践

一、风险与目标风险：任意路径读取、MIME嗅探、内联脚本执行、文件名注入与目录遍历。目标：路径规范化与扩展名白名单、精确`Content-Type`与`nosniff`、安全`Content-Disposition`与UTF-8文件名。二、路径与类型校验import path from 'path' function normalizeSafe(root: string, rel: string): string | null { const p = path.normalize('/' + rel).replace(/^\/+/, '') const full = path.join(root, p) if (!full.startsWith(path.join(root, path.sep))) return null return full } const mimeMap: Record<string, string> = { '.pdf': 'application/pdf', '.txt': 'text/plain; charset=utf-8', '.csv': 'text/csv; charset=utf-8', '.zip': 'application/zip' } function contentTypeOf(ext: string): string | null { return mimeMap[ext.toLowerCase()] || null } 三、文件名规范化function safeFileName(name: string): string { const s = name.replace(/[\r\n\u0000]/g, '').replace(/[/\\]/g, '_') return s.slice(0, 200) } function disposition(name: string): string { const n = safeFileName(name) const encoded = encodeURIComponent(n) return `attachment; filename="${n}"; filename*=UTF-8''${encoded}` } 四、下载响应示例type Res = { setHeader: (k: string, v: string) => void; status: (n: number) => Res; end: (b?: string) => void } function sendDownload(res: Res, full: string, downloadName: string, fs: any) { const ext = path.extname(full) const ct = contentTypeOf(ext) if (!ct) return res.status(415).end('unsupported_media_type') res.setHeader('Content-Type', ct) res.setHeader('X-Content-Type-Options', 'nosniff') res.setHeader('Content-Disposition', disposition(downloadName)) res.setHeader('Cache-Control', 'private, max-age=0, no-store') const buf = fs.readFileSync(full) res.end(buf.toString('binary')) } 五、整合路由与验收type Req = { query: Record<string, string | undefined> } function handleDownload(req: Req, res: Res, fs: any) { const root = '/var/app/files' const rel = req.query['file'] || '' const name = req.query['name'] || 'download' const full = normalizeSafe(root, rel) if (!full) return res.status(400).end('invalid_path') sendDownload(res, full, name, fs) } 路径规范化通过且限制在根目录；扩展名白名单有效；`Content-Type`与`nosniff`设置正确。`Content-Disposition`为`attachment`且包含UTF-8文件名；缓存策略为私有且不存储。对不支持类型返回`415`；异常路径返回`400`；审计包含下载名与相对路径。