Go FileTransportFS 为什么只接受 file 协议请求

NewFileTransportFS 常被说成“只接受 file 协议”，更准确的解释是：标准写法把它注册到 http.Transport 的 file scheme 下，因此只有 file:// 请求会被分派给它。这个限制主要发生在外层协议路由，不是 NewFileTransportFS 内部主动检查并拒绝 http 或 https。

想让同一个 http.Client 同时访问本地文件和网络地址，应使用 Transport.RegisterProtocol("file", ...)；不要直接把文件 RoundTripper 替换成整个 Client 的 Transport，否则所有 scheme 都可能进入文件处理逻辑。

Go 标准库文档：https://pkg.go.dev/net/http#NewFileTransportFS

限制不是 NewFileTransportFS 自己加的

http.Client 把请求交给它持有的 RoundTripper。普通场景里这个对象是 *http.Transport，它原本就负责 HTTP 和 HTTPS。当调用 RegisterProtocol 后，Transport 会多保存一张“scheme 到 RoundTripper”的映射表；请求到来时，它读取 req.URL.Scheme，有匹配项就转交给注册对象。

因此下面这行配置的真正含义不是让 NewFileTransportFS 学会识别 file，而是告诉外层 Transport：“看到 file scheme 时，请改用这个文件 RoundTripper。”

tr.RegisterProtocol("file", http.NewFileTransportFS(fsys)) // 仅把 file scheme 分派给文件传输器

Go 源码里的 fileTransport.RoundTrip 会直接把请求交给文件处理器，并没有再次判断 scheme。外层的 Transport.alternateRoundTripper 才会按 req.URL.Scheme 查询注册映射。这也是为什么“只接受 file 协议”在典型配置中成立，但不能理解成该 RoundTripper 自带硬编码白名单。

Go 1.22 前后的接口差异

NewFileTransportFS 在 Go 1.22 加入，参数是标准的 fs.FS。更早的 NewFileTransport 接收 http.FileSystem。两者目标相同，都是生成读取文件系统内容的 RoundTripper，区别主要在文件系统接口。

这不是破坏性替换，旧接口并未因为新函数出现就自动失效。只有项目已经以 fs.FS 为核心抽象，或者希望减少适配层时，迁移才有直接收益。迁移后要特别检查底层返回的文件是否实现 io.Seeker。

正确注册 file 协议

下面示例把当前目录限制为文件根目录，再为独立 Client 注册 file scheme。这样 file:///testdata/readme.txt 会从当前目录下读取对应文件，而同一个 Transport 仍保留普通 HTTP/HTTPS 能力。

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    fsys := os.DirFS(".") // 将当前目录作为受限文件根目录

    tr := &http.Transport{}
    tr.RegisterProtocol(
        "file",
        http.NewFileTransportFS(fsys), // 只为 file scheme 注册文件传输器
    )
    client := &http.Client{Transport: tr}

    resp, err := client.Get("file:///testdata/readme.txt")
    if err != nil {
        panic(err) // 真实项目应改为返回带上下文的错误
    }
    defer resp.Body.Close() // 及时关闭响应体，避免资源泄漏

    if resp.StatusCode != http.StatusOK {
        panic(fmt.Errorf("读取文件失败：%s", resp.Status))
    }
    if _, err := io.Copy(os.Stdout, resp.Body); err != nil {
        panic(err) // 检查复制阶段的读取错误
    }
}

URL 使用三个斜杠是因为 host 留空，资源路径放在 Path 中。对于 os.DirFS(".")，文件传输器会通过适配层把 URL 路径映射到这个根目录，不能把它当成任意系统绝对路径访问器。

为什么直接替换 Transport 会产生误解

下面这种写法在类型上没有问题，但它把文件 RoundTripper 直接设置成 Client 的唯一 Transport。此时请求不会先经过 *http.Transport 的 scheme 分派，NewFileTransportFS 会直接收到调用方传入的请求。

client := &http.Client{
    Transport: http.NewFileTransportFS(os.DirFS(".")), // 所有请求都直接进入文件处理器
}

// 即使写成 https，文件传输器仍主要按 URL.Path 查找本地资源。
resp, err := client.Get("https://example.invalid/readme.txt")
_ = resp
_ = err

这种配置不适合混合访问本地文件和网络资源，也容易让人误以为 Host 会参与定位。标准库文档明确说明，返回的 RoundTripper 会忽略 URL host 以及请求的大多数其他属性。要保留清楚的协议边界，应把它注册到 file scheme，而不是把它当作通用网络 Transport。

路径和文件系统还有两个边界

第一，Host 被忽略，Path 才是资源定位依据。像 file://server/docs/a.txt 这样的写法不会自动变成网络共享访问。不要把 file URL 的 host 当成远端主机名，也不要依赖它做租户或权限隔离。

第二，文件必须支持 Seek。NewFileTransportFS 的文档要求 fs.FS 返回的文件实现 io.Seeker。这是因为文件响应可能需要探测大小、处理范围请求或调整读取位置。自定义内存文件系统若只实现 Read 和 Close，就可能在实际读取时失败。

常见错误怎么判断

迁移和回归检查清单

• 确认构建环境至少为 Go 1.22，旧版本没有 NewFileTransportFS。
• 确认传入对象实现的是 fs.FS，不是只满足旧 http.FileSystem。
• 用独立 *http.Transport 注册 file scheme，避免修改共享的默认 Transport。
• 分别回归一个 file:// 请求和一个普通 HTTP/HTTPS 请求，确认分派边界正确。
• 测试存在文件、缺失文件、目录、范围读取和大文件，确认底层文件支持 Seek。
• 不要把不可信用户输入直接拼成文件 URL；文件根目录和可访问路径仍要由业务限制。

相关问题

FileTransportFS 能访问远程 file 主机吗？

不能按普通理解自动访问远程主机。它忽略 URL host，并从传入的 fs.FS 读取内容；远程文件系统必须由你提供相应的 fs.FS 实现。

可以直接修改 http.DefaultTransport 吗？

技术上可以取得具体 Transport 后注册协议，但共享全局对象会影响同进程其他调用者。更稳妥的做法是为需要 file 协议的功能创建独立 Client。

NewFileTransport 现在必须迁移吗？

不必须。现有 http.FileSystem 代码可以继续使用旧函数；当项目已经统一采用 fs.FS 时，再迁移通常更自然。

总结

NewFileTransportFS 与 file 协议的绑定来自 http.Transport.RegisterProtocol 的 scheme 分派。它本身只是一个把请求路径映射到 fs.FS 的 RoundTripper。理解这层职责后，排错就很直接：先看 file scheme 是否注册，再看 URL.Path 是否落在正确根目录，最后检查底层文件是否支持 io.Seeker。如果 Client 还要访问网络，保留普通 Transport 并注册 file 协议，比直接替换整个 Transport 更安全也更清晰。