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

pyscript 无法加载本地 python 模块常因路径配置错误或缺少本地服务器导致；本文详解如何正确配置 `py-config` 的 `fetch` 路径、启用本地 http 服务，并适配最新 pyscript 版本规范。

在 PyScript 中通过 from ... import ... 导入本地模块（如 BookOperations.py）时，出现 404 (File not Found) 错误，根本原因并非路径写法本身错误，而是浏览器环境无法直接读取本地文件系统——PyScript 依赖 HTTP 请求动态加载 .py 文件，因此必须通过 Web 服务器提供服务，而不能双击 HTML 文件直接打开（即 file:// 协议）。

✅ 正确做法一：启动本地 HTTP 服务器

PyScript 不支持 file:// 协议下的模块加载。请使用以下任一方式启动本地服务器：

Python 内置服务器（推荐，无需额外安装）：
```
# 在项目根目录（含 index.html 的目录）执行
python -m http.server 8000
```
然后访问 http://localhost:8000/your-page.html。
VS Code Live Server 插件：右键 HTML 文件 → “Open with Live Server”。
其他工具：live-server、http-server（npm）、或任何静态文件服务器。

⚠️ 注意：确保 ../app/db_operations/BookOperations.py 相对于你启动服务器的根目录是可访问的。例如，若服务器根目录为 /my-project/，且你的文件结构为： /my-project/ ├── index.html └── app/ └── db_operations/ └── BookOperations.py则路径应为 ./app/db_operations/BookOperations.py（以 index.html 所在位置为基准）。

✅ 正确做法二：使用最新 PyScript 配置语法

Alpha 版本中的已废弃。当前稳定版（如 2025.12.1+ 或最新 2025.x）需改用 + fetch 配置：




  
  
  Title

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


  
    from BookOperations import get_books_count
    print("Loaded successfully:", get_books_count())

? 关键说明：

fetch 是一个对象数组，每个对象指定源路径（from，相对于服务器根目录）和目标文件名（to，将被加载到 Python 模块命名空间中）；
to 值即为你 import 时使用的模块名（不含 .py 后缀），因此 to: "BookOperations.py" → 可 import BookOperations 或 from BookOperations import ...；
packages = [] 显式声明无额外 PyPI 包依赖（避免隐式尝试 pip 安装）；
请始终使用最新稳定版 CDN 链接替换旧 Alpha 地址（如 https://pyscript.net/alpha/... 已停用）。

? 调试技巧与注意事项

浏览器开发者工具（F12）→ Network 标签页：检查 BookOperations.py 是否返回 200；若为 404，请核对服务器根目录与 from 路径是否匹配；
PyScript 会自动将 fetch 中的 to 文件注册为顶层模块，无需 __init__.py，但模块内不能有未满足的相对导入；
若模块依赖其他本地 .py 文件，请全部列在 fetch 数组中；
避免使用 .. 跨出服务器根目录（安全限制），所有路径必须位于服务可访问范围内。

遵循以上步骤，即可彻底解决 PyScript 本地模块 404 加载失败问题，实现可靠、可维护的模块化开发。