Go filepath 与 path 处理本地路径和 URL 的区别

Go 里选择 filepath 还是 path，关键不在于字符串看起来像不像路径，而在于它最终要交给谁：要访问当前操作系统上的文件，就用 path/filepath；要构造 URL 或其他固定使用正斜杠的逻辑路径，就用 path。如果还涉及查询参数、转义或主机名，再把 URL 交给 net/url，不要把它们都当成普通文件名拼接。

官方资料（复制地址查看）：https://pkg.go.dev/path/filepath、https://pkg.go.dev/path、https://pkg.go.dev/net/url。

先看数据最终要落在哪里

一个上传服务经常同时处理三种字符串：用户提交的文件名、服务器磁盘上的保存位置、返回给浏览器的资源地址。它们都可能包含目录层级，但语义并不相同。文件名和磁盘位置属于操作系统；资源地址属于 URL；如果把其中一条结果直接复用到另一条边界，问题通常要到 Windows、反向代理或特殊字符出现时才暴露。

可以先用下面这张决策表压缩判断：

比较 filepath 与 path 的职责

filepath 的定位是“与目标操作系统文件路径兼容”。在使用反斜杠的系统上，它的连接和清理规则会围绕系统分隔符工作；path 则只处理斜杠分隔的路径，官方文档明确把 URL 作为典型使用场景。两者都提供 Join、Clean、Base、Dir 等相似名称，但相似的函数名不代表输入语义可以互换。

例如，程序要读取配置文件时，目录拼接应留给 filepath.Join；程序要生成 /assets/css/site.css 这样的资源路径时，则应使用 path.Join。在类 Unix 环境中两者的输出可能看起来一样，不能因此把选择写死为“哪个能跑就用哪个”。

把本地磁盘与 URL 地址拆成两条边界

推荐把本地保存路径和对外资源路径分别建模。下面的示例只展示边界设计：用户输入先取文件名，磁盘位置用 filepath，对外相对路径用 path；完整 URL 的主机、协议和转义仍由 net/url 负责。示例没有连接真实存储，也不宣称已经执行。

package asset

import (
    "net/url"
    "path"
    "path/filepath"
)

// Locations 同时保存磁盘位置和对外资源路径，避免调用方混用字符串。
type Locations struct {
    DiskPath string
    URLPath  string
}

// BuildLocations 把文件系统语义和 URL 语义分到各自的标准库包。
func BuildLocations(root, publicRoot, userName string) Locations {
    // Base 只保留文件名，防止用户提交的目录片段直接进入保存目录。
    name := filepath.Base(userName)
    // 磁盘路径遵循当前操作系统的分隔符。
    diskPath := filepath.Join(root, "uploads", name)
    // 对外路径固定使用正斜杠，适合作为 URL 的 Path 部分。
    relative := path.Join(publicRoot, "uploads", name)
    return Locations{DiskPath: diskPath, URLPath: relative}
}

// ResourceURL 将已确定的 URL 路径放入 URL 结构，不手写查询串。
func ResourceURL(scheme, host, resourcePath string) string {
    // Path 字段由 net/url 负责编码和组合 URL 组件。
    u := url.URL{Scheme: scheme, Host: host, Path: resourcePath}
    return u.String()
}

这里的重点不是把 filepath.Base 当成完整的安全策略，而是让每一步的输出类型更容易被审查：DiskPath 是本地文件系统位置，URLPath 是对外路径。真正的上传服务还应结合允许的扩展名、存储权限、文件内容检查和覆盖策略；不能只靠路径清理解决所有文件上传风险。

方案对比：什么时候不能把 filepath 换成 path

如果调用的是 os.Open、os.WriteFile、filepath.Walk 或其他本地文件 API，路径必须能被当前系统正确解释。把 URL 中的正斜杠直接当成本地路径，可能在某些系统上碰巧可用，但无法表达盘符、卷名或系统专属分隔符。

反过来，若要拼接静态资源地址、路由片段或归档包内部的固定路径，使用 filepath.Join 会把平台差异带进协议数据。部署环境一换，输出可能出现反斜杠，浏览器、对象存储或签名逻辑就不一定按预期处理。此时 path.Join 的固定正斜杠正是需要的约束。

还有一类情况不能只在两个包中二选一：https://example.com/a%2Fb?raw=1 是完整 URL，不是文件系统路径。主机、路径、查询和片段应交给 net/url.URL 的字段表达；不要先把整个字符串送进 path.Clean，否则问号、井号和转义字符的边界会被混入路径规则。

跨平台风险集中在三个细节

第一，测试不能只在使用正斜杠的系统上比较字符串。对本地路径，优先比较经过 filepath.Clean 的结果或实际文件操作；对 URL 路径，明确期望值必须是正斜杠。不要把某台开发机的字面量当成所有平台的契约。

第二，Windows 盘符不是 URL 的主机名。C:\\data\\a.txt 属于文件系统语义；如果要把本地文件映射成资源 URL，应先确定映射关系，再用 path.Join 生成资源路径，而不是对盘符字符串做一次 path.Join 就当成 URL。

第三，文件名、URL 路径段和查询参数的转义责任不同。用户文件名可能包含空格或非 ASCII 字符，资源地址还可能需要 URL 编码；filepath 与 path 负责路径结构，不负责替你设计完整的输入校验、权限策略或 URL 查询参数。

落地清单：把选择写进代码边界

• 要读写本机文件时，导入 path/filepath，不要凭开发机输出选择包。
• 要生成 URL、路由或归档内部的固定斜杠路径时，使用 path。
• 需要协议、主机、查询参数或转义时，使用 net/url 的组件字段。
• 本地路径和对外地址分别命名、分别测试，避免一个 string 在多个边界反复复用。
• 对用户文件名先做文件名级处理，并把权限、覆盖、扩展名和内容检查放在明确的业务层。
• 至少加入一组跨平台路径用例和一组 URL 正斜杠用例，检查的是语义而不是某台机器的偶然字面量。

一句话总结：filepath 解决“当前系统怎样找到文件”，path 解决“固定斜杠的逻辑路径怎样组合”，net/url 解决“完整 URL 的各个组件怎样表达”。先确定数据去向，再选择包，跨平台路径问题就不会靠运气。