Go multipart.Part FileName 什么时候会返回空字符串

在处理 multipart/form-data 时，part.FileName() 返回空字符串并不一定是解析失败。它读取的是当前分段的 Content-Disposition 头中的 filename 参数；普通表单字段通常只有 name，没有文件名，所以返回空字符串是正常结果。

一句话判断：先看当前 Part 是否真的带有文件名参数，再决定是否进入文件保存逻辑。不要用 FileName() == "" 去证明整个 multipart 请求为空。

FileName 读取的到底是哪一段信息

mime/multipart.Part 代表 multipart body 中的一个分段。Go 官方文档对 FileName 的定义是：读取该 Part 的 Content-Disposition 头里的 filename 参数；如果文件名非空，还会通过平台相关的 filepath.Base 处理后再返回。

这里有三个容易混淆的名字：

因此，FileName() 不会从 body 内容里猜文件名，也不会因为分段有数据就自动生成一个文件名。文件名是否存在，取决于上游构造的头部参数。

为什么普通字段通常拿不到文件名

一个普通文本字段通常长这样：

Content-Disposition: form-data; name="title"

季度报告

它有 name，没有 filename，所以 part.FormName() 可能返回 title，而 part.FileName() 返回空字符串。此时空值表达的是“这个 Part 没有可用文件名”，不是“读取失败”。

文件分段通常还会有 filename：

Content-Disposition: form-data; name="avatar"; filename="portrait.png"

...文件内容...

这时 FormName() 关注字段名 avatar，FileName() 关注文件名 portrait.png。两者是同一个分段里的两种不同元数据。

用两个方法先判断当前 Part 的用途

遍历 Reader.NextPart() 时，可以把字段名和文件名同时读出来，再把业务分支写清楚：

package main

import (
    "fmt"
    "io"
    "mime/multipart"
    "strings"
)

func main() {
    raw := "--demo\\r\\n" +
        "Content-Disposition: form-data; name=\\"title\\"\\r\\n\\r\\n" +
        "季度报告\\r\\n" +
        "--demo--\\r\\n"

    reader := multipart.NewReader(strings.NewReader(raw), "demo")
    for {
        part, err := reader.NextPart()
        if err == io.EOF {
            break // 所有分段都已读完，正常结束遍历。
        }
        if err != nil {
            panic(err) // 解析错误要停止当前请求，不能把坏数据当成字段。
        }

        fieldName := part.FormName()
        fileName := part.FileName()
        fmt.Printf("field=%q file=%q\\n", fieldName, fileName)
    }
}

这个例子输出的文件名为空，是因为原始分段只有 name。如果把头部换成带 filename 的形式，FileName() 才有机会返回非空字符串。

filename 缺失、为空和带路径分别意味着什么

实际排查时，至少要区分下面三种状态：

• 没有 filename 参数：常见于普通字段，也可能是上游只发送了不完整的文件分段；FileName() 返回空字符串。
• filename=""：头部明确携带了空文件名，返回值仍然为空；这和“文件内容一定不存在”不是同一个结论。
• filename="目录/portrait.png"：有非空文件名时，Go 会用 filepath.Base 取基础名，调用方不应把返回值当作原始客户端路径。

如果业务需要保留完整的原始头部，应该单独读取 part.Header 并按照自己的记录规则存档；如果只是为了生成服务器侧文件名，则使用 FileName() 的非空结果并再次做业务约束更合适。

上传处理不要把空文件名直接当成异常

一个更稳妥的处理方式，是先读文件名，再决定是普通字段、空文件分段还是可处理的文件分段：

func classifyPart(part *multipart.Part) (string, error) {
    fieldName := part.FormName()
    fileName := part.FileName()

    if fileName == "" {
        // 没有文件名时保留字段名，交给普通字段或空文件策略处理。
        if fieldName == "" {
            return "unknown-part", nil
        }
        return "form-field:" + fieldName, nil
    }

    // FileName 已按 filepath.Base 处理，不把客户端路径当作服务端路径使用。
    return "file-part:" + fileName, nil
}

这个分支的重点不是把所有空值都接受下来，而是把语义分开：普通字段可以继续读取 body 作为文本；空文件名的分段可以按产品约定忽略或提示；真正带文件名的分段才进入文件内容处理。若业务要求“必须上传文件”，就应该在文件分支中明确报错，而不是把所有 FileName() 为空的 Part 都解释成 multipart 解析失败。

用最小分段复查误判来源

遇到 FileName() 为空时，按这个顺序检查即可：

1. 先看 part.FormName() 是否有值；有值且没有文件名，通常是普通字段。
2. 再看 part.Header.Get("Content-Disposition") 是否包含 filename 参数；没有参数就不要期待 FileName() 返回文件名。
3. 如果有 filename=""，把它和文件内容为空分开记录；文件名和 body 是两层信息。
4. 如果文件名非空，使用返回的基础名，不要直接拼接客户端提供的目录字符串。

可以用一份包含普通字段、带文件名文件字段和空文件名字段的最小请求，分别观察三个 Part 的头部和返回值。这个检查只是在定位请求格式，不需要把 FileName() 当成文件内容是否存在的唯一判断。

常见追问

FileName 为空时还能读取 Part body 吗？

可以。FileName() 只反映文件名参数；分段 body 是否有内容要通过 Read 等方式另行处理。

FormName 和 FileName 可以同时为空吗？

可以。如果分段缺少符合预期的 Content-Disposition 参数，两者都可能没有可返回的值。业务代码应把它当成需要解释的输入，而不是自动补一个文件名。

FileName 返回的是客户端完整路径吗？

不是。官方文档说明非空文件名会经过 filepath.Base 处理，调用方仍需自行决定服务器端保存名、冲突策略和目录位置。

总结：multipart.Part.FileName() 返回空字符串，最常见原因是当前分段没有非空的 filename 参数。先用 FormName() 判断字段身份，再根据文件名参数状态选择普通字段、空文件分段或文件处理分支，排查就不会把正常的 multipart 语义误报成解析故障。