PyScript 文件导入失败（404）的完整解决方案_技术教程

pyscript 无法加载本地 python 模块常因路径配置错误或缺少本地服务器导致；本文详解正确配置 `py-config` 的 `fetch` 选项、启用本地 http 服务及路径书写规范，助你可靠导入自定义模块。

在 PyScript 中从本地文件导入模块（如 BookOperations.py）时出现 404 (File not found) 错误，根本原因通常有两个：一是浏览器直接双击打开 HTML 文件（file:// 协议），导致跨域限制和静态资源无法被 PyScript 的 Fetch API 正确读取；二是旧版 py-env 中的 paths 配置已被弃用，新版本需使用标准化的 py-config + fetch 语法。

✅ 第一步：必须使用本地 HTTP 服务器
浏览器禁止 file:// 协议下发起跨文件 fetch 请求。请勿双击 HTML 打开，而应启动一个本地服务器：

✅ 推荐（VS Code 用户）：安装 Live Server 插件，右键 HTML 文件 → “Open with Live Server”。
✅ Python 内置服务器（任意平台）：
```
# 在项目根目录（含 index.html 的同级目录）执行：
python -m http.server 8000
```
然后访问 http://localhost:8000/index.html。

⚠️ 若未启用服务器，无论路径如何修正，均会触发 404 —— 这是浏览器安全策略，非 PyScript 缺陷。

✅ 第二步：升级并正确配置 py-config（替代已废弃的 py-env）
PyScript 自 2025.12.1 起已移除 py-env 中的 paths，改用标签配合 fetch 字段，支持更灵活的路径映射与别名：




  
  
  Book App

  
  
    {
      "packages": [],
      "fetch": [
        {
          "from": "./app/db_operations/BookOperations.py",
          "to": "./BookOperations.py"
        }
      ]
    }
  


  
    # ✅ 现在可直接按模块名导入（无需路径前缀）
    from BookOperations import get_books_count
    print("Import successful! Count:", get_books_count())

? 关键说明：

from 字段：必须是可通过 HTTP 访问的相对 URL 路径（如 ./app/db_operations/BookOperations.py），对应你项目中真实的文件位置（参考你的截图结构）；
to 字段：指定该文件在 PyScript 虚拟文件系统中的目标路径（通常设为同名 .py 文件即可），导入时使用 to 的文件名（不含路径）；
所有路径均以 ./ 开头，表示相对于当前 HTML 所在目录（即服务器根目录）；
❌ 不要写 ../（上级目录在 HTTP 服务中可能不可达）、❌ 不要写 app.db_operations.BookOperations（这不是 Python 包导入，而是文件 fetch 映射）。

✅ 第三步：验证文件可访问性
在浏览器中直接访问 http://localhost:8000/app/db_operations/BookOperations.py —— 若能正常显示 Python 源码，则路径配置正确；若 404，请检查文件实际位置是否与 from 值完全一致（区分大小写、.py 后缀、无隐藏字符）。

? 额外建议：