如何在 PyScript 中安全加载和使用外部文件

PyScript 无法直接访问本地文件系统，但可通过配置 py-config 的 files 键，将网络可访问的文件预加载至其内置虚拟文件系统，从而在 Python 代码中使用 open() 等标准 I/O 函数正常读取。

pyscript 无法直接访问本地文件系统，但可通过配置 `py-config` 的 `files` 键，将网络可访问的文件预加载至其内置虚拟文件系统，从而在 python 代码中使用 `open()` 等标准 i/o 函数正常读取。

在 PyScript 环境中，浏览器沙箱机制严格限制了对本地文件系统的直接访问（如 open(“data.txt”) 会触发 FileNotFoundError），这是出于安全考虑的强制约束。但实际开发中，常需加载配置、CSV、json 或文本数据等资源。PyScript 提供了安全、声明式的解决方案：通过 标签的 files 配置项，将远程或本地开发服务器托管的文件预先下载并挂载到内存中的虚拟文件系统（VFS），之后即可像操作普通文件一样使用 open()、json.load()、pandas.read_csv() 等函数。

✅ 正确做法：使用 files 配置加载文件

确保目标文件可通过 http 访问（例如部署在 github Pages、Vercel，或本地启动简易服务器）：

# 在项目根目录启动 Python 内置服务器（端口 8000） python3 -m http.server 8000

此时，./data/config.json 可通过 http://localhost:8000/data/config.json 访问。

在 HTML 中配置 py-config：

<py-config> {   "packages": ["pandas"],   "files": [     "/data/config.json",     "/assets/sample.csv"   ] } </py-config>

? 注意：路径为相对于当前页面 URL 的完整路径（支持绝对路径 /data/… 或相对路径 data/…），PyScript 会自动发起 fetch 请求并将其写入 VFS 的对应路径。

随后，在 中可直接读取：

# 成功读取 —— 文件已存在于虚拟文件系统中 with open("/data/config.json", "r") as f:     config = json.load(f)     print("Loaded config:", config)  import pandas as pd df = pd.read_csv("/assets/sample.csv") print(df.head())

⚠️ 重要注意事项

• 文件必须可跨域访问：若文件托管在第三方服务，请确保响应头包含 access-Control-Allow-Origin: *（或明确允许你的域名），否则浏览器会因 CORS 拒绝请求。
• 路径大小写敏感：VFS 路径与 files 列表中声明的路径必须完全一致（包括大小写和斜杠方向）。
• 不支持动态上传或写入：files 仅支持只读预加载；运行时无法创建新文件或修改已加载文件（VFS 是只读挂载）。
• 避免使用已废弃的 [[fetch]]：旧版文档中的 [[fetch]] 配置逻辑复杂、易出错，官方已明确推荐统一使用更简洁可靠的 files 数组。

✅ 总结

只要将文件托管在 Web 可达位置，并在 中通过 files 显式声明，PyScript 就能自动完成“下载 → 解析 → 挂载至虚拟文件系统”的全过程。开发者无需手动处理 fetch 或 Blob，即可无缝复用标准 Python 文件操作习惯。这是兼顾安全性、易用性与兼容性的最佳实践。