Go multipart.FileHeader Filename 为什么不能直接拼接本地路径

multipart.FileHeader.Filename 不能直接作为服务器本地路径的一部分，因为它本质上来自客户端提交的 Content-Disposition 元数据。Go 在解析 multipart part 时会对非空文件名调用平台相关的 filepath.Base，但这只是在解析层丢弃部分目录信息，不代表这个名称已经通过了你的存储策略。重名覆盖、跨平台分隔符差异、特殊名称、扩展名伪装和后续下载展示仍然需要应用自己处理。

稳妥做法是把它拆成两份数据：原始文件名只用于展示或审计，服务器另行生成存储名。本地目标路径只能由受控的上传根目录与服务器生成的文件名组成。

Go 官方文档：https://pkg.go.dev/mime/multipart

Filename 来自哪里，Go 已经做了什么

浏览器或其他 HTTP 客户端上传文件时，通常会在 multipart part 的 Content-Disposition 头中携带 filename 参数。Go 的 mime/multipart 解析器读取这个参数，通过 Part.FileName() 得到文件名，然后写入 FileHeader.Filename。

官方源码明确写明：当文件名非空时，Part.FileName() 会先经过 filepath.Base。这符合 multipart 规范中不应使用客户端目录路径信息的要求。不过 filepath.Base 是平台相关操作，而且它解决的是“取基础名”，不是“允许写入服务器文件系统”。

官方源码：https://go.dev/src/mime/multipart/multipart.go

为什么直接 Join 仍然不是可靠边界

很多上传代码看起来只差一行：

// 错误示例：客户端文件名直接参与服务器路径决策
dstPath := filepath.Join(uploadDir, fileHeader.Filename)

// 错误示例：重名时还可能覆盖已有文件
dst, err := os.Create(dstPath)

这段代码的问题不是说每个文件名都会突破目录，而是它把服务器最关键的存储决策交给了客户端。即使基础名处理挡住了某些目录片段，仍然存在以下边界：

• 重名覆盖：两个用户都上传 avatar.png，后一个请求可能替换前一个文件。
• 平台差异：filepath.Base 按服务器操作系统解释路径分隔符；在一台系统上普通的字符，在另一台系统上可能具有路径语义。
• 特殊文件名：空名、点文件、尾随点、控制字符、超长名称以及 Windows 保留名称不适合直接落盘。
• 扩展名不可信：.jpg 只是字符串后缀，不能证明内容一定是图片。
• 目录策略缺失：业务通常还需要按租户、日期或记录 ID 隔离，而原始文件名无法表达这些权限边界。

filepath.Clean、filepath.Base 或 filepath.IsLocal 都有各自用途，但它们不能替代“由谁生成存储名、谁能写哪个目录、同名如何处理”的应用策略。尤其是 IsLocal 只做词法分析，不考虑文件系统中符号链接的影响。

filepath 官方文档：https://pkg.go.dev/path/filepath

把显示名和存储名分开

最简单的安全模型是三层：客户端提供显示名；服务器只从显示名中提取被允许的扩展名；服务器使用随机字节或业务记录 ID 生成真正的存储名。这样，原始名称无论是什么，都不会直接控制本地路径。

下面的函数只保留允许的扩展名，并用 crypto/rand 生成随机存储名。扩展名白名单应按业务类型调整；如果业务不需要保留扩展名，也可以完全省略它。

package upload

import (
    "crypto/rand"
    "encoding/hex"
    "fmt"
    "path/filepath"
    "strings"
)

var allowedExt = map[string]struct{}{
    ".jpg": {},
    ".jpeg": {},
    ".png": {},
    ".webp": {},
}

func newStoredName(originalName string) (string, error) {
    // 原始名称只用于提取候选后缀，不参与目录拼接
    ext := strings.ToLower(filepath.Ext(originalName))
    if _, ok := allowedExt[ext]; !ok {
        return "", fmt.Errorf("不允许的文件扩展名: %q", ext)
    }

    // 存储名由服务器随机生成，避免重名和客户端控制
    var token [16]byte
    if _, err := rand.Read(token[:]); err != nil {
        return "", fmt.Errorf("生成存储名: %w", err)
    }
    return hex.EncodeToString(token[:]) + ext, nil
}

这里保留扩展名是为了后续管理方便，并不是文件类型校验的全部。正式上传接口还应设置请求体上限、限制单文件大小，并按业务需要检查实际内容类型。客户端传来的 MIME 头同样不能作为唯一依据。

完成上传文件的保存与清理

FileHeader.Open() 返回的 multipart.File 可能来自内存，也可能来自解析器创建的临时文件。调用方只需要按接口读取，但必须及时关闭。目标文件建议使用 O_EXCL 独占创建，避免意外覆盖。

package upload

import (
    "fmt"
    "io"
    "mime/multipart"
    "os"
    "path/filepath"
)

func SaveFile(uploadDir string, fh *multipart.FileHeader) (string, error) {
    // 上传根目录由服务器配置，不能来自请求参数
    if err := os.MkdirAll(uploadDir, 0o750); err != nil {
        return "", fmt.Errorf("创建上传目录: %w", err)
    }

    storedName, err := newStoredName(fh.Filename)
    if err != nil {
        return "", err
    }
    dstPath := filepath.Join(uploadDir, storedName)

    // Open 读取 multipart 内容，底层可能是内存或临时文件
    src, err := fh.Open()
    if err != nil {
        return "", fmt.Errorf("打开上传内容: %w", err)
    }
    defer src.Close()

    // O_EXCL 保证同名目标存在时失败，不覆盖历史文件
    dst, err := os.OpenFile(dstPath, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
    if err != nil {
        return "", fmt.Errorf("创建目标文件: %w", err)
    }

    ok := false
    defer func() {
        // 复制失败时删除不完整文件，避免被后续流程误用
        dst.Close()
        if !ok {
            _ = os.Remove(dstPath)
        }
    }()

    if _, err := io.Copy(dst, src); err != nil {
        return "", fmt.Errorf("写入上传内容: %w", err)
    }
    if err := dst.Close(); err != nil {
        return "", fmt.Errorf("关闭目标文件: %w", err)
    }
    ok = true
    return storedName, nil
}

这段代码返回的是 storedName，而不是完整本地路径。业务层可以把它与记录 ID 一起写入数据库，下载时再从固定根目录构造路径。不要把服务器绝对路径返回给客户端。

如果代码显式调用了 Request.ParseMultipartForm，请求处理结束后还应清理解析器可能创建的临时文件。通常可以在解析成功后安排：

if err := r.ParseMultipartForm(32 

ParseMultipartForm 的参数是文件部分可用于内存的阈值，不等于整个请求的最大大小。HTTP 层仍应配合 http.MaxBytesReader 或网关限制控制总请求体，业务层再校验每个文件的大小和数量。

保存后如何关联下载名称

上传完成后，一条文件记录至少可以包含 recordID、originalName、storedName、大小、内容类型和创建时间。storedName 用于定位服务器文件，originalName 只用于界面展示或下载响应，两者不要互换。

原始显示名入库前可以做长度限制、控制字符移除和 Unicode 规范化，但这些操作是为了展示稳定，不是为了让它重新获得路径权限。下载时设置 Content-Disposition 也应使用标准库正确编码，而不是直接把原始字符串拼进响应头。

常见误区和边界

再调用一次 filepath.Base 就够了吗？

不够。Go 的 multipart 解析已经对非空文件名调用过一次平台相关的 filepath.Base。重复调用可以作为防御性整理，但不能解决重名、扩展名白名单、服务器保留名、目录隔离和下载展示问题。最关键的边界仍是服务器生成存储名。

可以用 filepath.IsLocal 检查后再 Join 吗？

filepath.IsLocal 很适合判断一个应用自己定义的相对路径是否在词法上保持本地性，但上传场景通常根本不需要接受客户端路径。只要业务目标是“保存一个文件”，生成单段服务器文件名比允许用户相对路径更简单。若业务确实允许目录层级，还必须单独设计权限、符号链接和并发创建边界。

保留原始扩展名会不会仍有风险？

扩展名只应从白名单中选择，并与实际内容检查、下载响应类型和后续处理策略配合。不要因为后缀是 .jpg 就把文件交给图像处理器，也不要把上传目录放到能直接执行脚本的 Web 根目录中。

随机名还会碰撞吗？

理论上任何有限随机空间都有碰撞可能，所以示例同时使用 O_EXCL。创建失败时可以重新生成一次新名称；不能退回覆盖模式。若已有数据库记录，也可以使用不可预测的记录 ID 或随机 ID 作为存储键。

为什么不直接使用客户端完整路径？

multipart 规范就要求目录路径信息不应被使用。客户端本机路径对服务器没有业务意义，还可能泄露环境信息或造成跨平台解析差异。服务器只需要一个展示名称和一个自己控制的存储键。

把路径决策留在服务器

FileHeader.Filename 有价值，但它的价值是告诉用户“上传时这个文件叫什么”，不是告诉服务器“应该写到哪里”。上传接口只要坚持三点，路径边界就会清楚很多：原始名只作元数据；存储名由服务器生成；目标目录来自服务器配置。再配合扩展名与内容检查、请求体限制、独占创建、错误清理和数据库权限校验，就能让 multipart 文件从输入到存储保持可控。