Python 3.14 pathlib.Path.from_uri 怎么解析文件 URI：主机名、百分号编码与平台边界

处理跨平台文件链接时，字符串形式的 file:///srv/reports/日报.csv 不能直接当成本地路径使用。Python 3.14 的 pathlib.Path.from_uri() 可以把它转换成 Path，但它只接受 file: URI，并且会根据主机名和运行平台决定是否接受。先记住一个结论：普通本地 URI 可以直接解析；带远程主机名的 URI 在 Windows 上可能变成 UNC 路径，在 Linux 和 macOS 上通常应该明确拒绝。

Path.from_uri() 负责 URI 到路径对象的转换，不负责判断文件是否存在；解析失败时捕获 ValueError，存在性检查再单独调用 Path.exists() 或 Path.stat()。

先用一个小工具验证 file URI

这个小工具只做两件事：调用 Path.from_uri()，然后把解析结果和存在性分开打印。不要在解析函数里顺手打开文件，这样 URI 格式错误、路径不存在和权限不足才能被区分。

from pathlib import Path

def parse_file_uri(uri: str) -> Path | None:
    try:
        path = Path.from_uri(uri)
    except ValueError as exc:
        print(f"invalid file URI: {exc}")
        return None

    print(f"path={path}")
    print(f"exists={path.exists()}")
    return path

parse_file_uri("file:///tmp/report%20final.csv")

成功状态有两个：第一，输出的是本机路径对象而不是原始 URI；第二，exists 只反映当前文件系统状态。文件不存在不代表 URI 解析失败。

file:、百分号编码和绝对路径分别怎么验收

Path.from_uri() 的入口约束很窄。file:///tmp/report%20final.csv 中的 %20 会还原为空格；https://example.com/a.txt 不是本地文件 URI，不能拿来调用这个方法。

若业务还要求文件必须存在，放在转换之后：

path = Path.from_uri("file:///tmp/report%20final.csv")
if not path.exists():
    raise FileNotFoundError(path)
text = path.read_text(encoding="utf-8")

这里的顺序很重要：Path.from_uri 解决的是表示法转换，exists 和 read_text 才会触碰文件系统。

主机名为什么会改变跨平台结果

URI 中的 authority 是 file://主机名/路径 里的主机部分。localhost 与本机主机名代表本地机器；其他主机名表示网络共享语义。Python 3.14 的官方文档明确区分了 Windows 和非 Windows 行为：Windows 可以返回 UNC 路径，其他平台对非空且非 localhost 的 authority 抛出 ValueError。

def parse_local_file_uri(uri: str) -> Path:
    path = Path.from_uri(uri)
    if not path.is_absolute():
        raise ValueError("file URI did not produce an absolute path")
    return path

parse_local_file_uri("file://localhost/tmp/report.csv")

不要只用字符串替换删除主机名。这样做会把一个本来需要拒绝的远程路径伪装成本地路径。让 Path.from_uri 按当前平台给出 UNC 或 ValueError，再由业务决定是否允许网络共享。

版本兼容：旧 Python 怎么保留同一条验收线

Path.from_uri() 是 Python 3.13 引入、在 Python 3.14 调整 authority 处理的 API。项目如果仍支持更早版本，不要无条件调用它；可以把兼容层集中到一个函数中，并明确只支持本地的 file: URI。

import sys
from pathlib import Path
from urllib.parse import unquote, urlsplit

def local_file_path(uri: str) -> Path:
    if sys.version_info >= (3, 13):
        return Path.from_uri(uri)

    parts = urlsplit(uri)
    if parts.scheme != "file" or parts.netloc not in ("", "localhost"):
        raise ValueError("only local file URI is supported")
    return Path(unquote(parts.path))

兼容层的验收仍然是同一套：协议不对要失败、远程 authority 要失败、百分号编码要还原、结果要是绝对路径。不要为了兼容旧版本而悄悄放开远程主机。

常见问题

Path.from_uri() 会自动下载 https 地址吗？

不会。它只处理 file: URI，不负责网络请求，也不会把远程 URL 变成本地文件。

解析成功就代表文件一定存在吗？

不代表。解析成功只说明 URI 能转换为路径；还要单独调用 exists() 或 stat()。

为什么 Linux 上的 file://server/share 可能失败？

因为非空且非 localhost 的 authority 是远程主机语义。官方规则允许 Windows 形成 UNC 路径，但非 Windows 平台会抛出 ValueError。

应该用 Path.as_uri() 还是 Path.from_uri()？

已有绝对路径要传成 URI 时用 as_uri()；收到 file: URI 要转回路径时用 from_uri()。两者方向相反，不能混用。

把边界留在转换层，后续代码更容易验收

一个稳定的处理流程是：先限制 file: 协议，再让 Path.from_uri() 处理编码和平台规则，随后单独做存在性、权限和业务目录检查。这样日志里能分清“URI 不合法”“路径不存在”和“文件不可读”，跨平台迁移时也不会靠字符串拼接猜 UNC 语义。