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”。
⚠️ 注意：确保 ../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 版本中的 <py-env> 已废弃。当前稳定版（如 2022.12.1+ 或最新 2024.x）需改用 <py-config> + fetch 配置：
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="https://www.php.cn/link/111df71156b0f9bf5df48fb11c3c46472024.8.1/pyscript.css" />
<script defer src="https://www.php.cn/link/111df71156b0f9bf5df48fb11c3c46472024.8.1/pyscript.js"></script>
<title>Title</title>
<py-config>
packages = []
fetch = [
{
"from": "./app/db_operations/BookOperations.py",
"to": "BookOperations.py"
}
]
</py-config>
</head>
<body>
<py-script>
from BookOperations import get_books_count
print("Loaded successfully:", get_books_count())
</py-script>
</body>
</html>? 关键说明：
- 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 加载失败问题，实现可靠、可维护的模块化开发。
