PyScript作为可以在浏览器中运行Python代码的工具，很多开发者在使用时会遇到文件导入返回404错误的情况，这类问题会直接导致依赖的Python脚本、数据文件无法加载，让整个功能无法正常运行。
常见404错误触发原因
PyScript文件导入404错误通常不是单一因素导致的，常见的原因有以下几种：
- 文件路径书写错误，比如相对路径层级不对、文件名大小写不匹配
- 本地开发时没有启动静态文件服务器，直接用本地文件协议打开页面
- 引用了外部CDN资源，但该资源地址已经失效或者网络无法访问
- 服务器没有正确配置静态资源访问规则，导致文件被拦截
分场景解决方案
本地开发环境排查
如果是在本地直接双击HTML文件打开页面，浏览器会使用file://协议加载资源，这种情况下PyScript很多资源加载逻辑会失效，很容易出现404错误。正确的做法是启动一个本地静态服务器，比如使用Python自带的http.server模块：
# 进入HTML文件所在目录，执行以下命令启动服务器 python -m http.server 8080
之后在浏览器访问http://127.0.0.1:8080/你的页面.html，就可以正常加载同目录下的Python文件了。如果是引用同目录下名为utils.py的文件，正确的引用方式如下：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>PyScript测试</title>
<link rel="stylesheet" href="https://pyscript.net/releases/2024.1.1/pyscript.css" />
<script defer src="https://pyscript.net/releases/2024.1.1/pyscript.js"></script>
</head>
<body>
<py-config>
[[fetch]]
files = ["./utils.py"]
</py-config>
<py-script>
import utils
print(utils.add(1, 2))
</py-script>
</body>
</html>
对应的utils.py文件内容如下：
def add(a, b):
return a + b
线上部署环境排查
如果是部署到线上服务器后出现404错误，首先要检查文件的部署路径是否和页面中引用的路径一致。如果是使用Nginx作为Web服务器，需要确保静态文件目录配置正确，比如所有.py文件放在/static/py/目录下，Nginx配置需要包含以下内容：
server {
listen 80;
server_name your_domain.com;
location /static/ {
root /var/www/your_project;
# 允许访问py文件，避免被默认规则拦截
types {
text/x-python py;
}
}
location / {
root /var/www/your_project;
index index.html;
}
}
此时页面中引用文件的路径需要写成/static/py/utils.py，对应的py-config配置修改为：
<py-config>
[[fetch]]
files = ["/static/py/utils.py"]
</py-config>
外部资源404处理
如果引用的是PyScript官方CDN之外的第三方资源，出现404错误时可以先检查资源地址是否仍然有效，也可以把资源下载到本地服务器再引用，避免外部资源失效的问题。如果是引用官方CDN的PyScript核心文件出现404，可以更换为官方最新版本的CDN地址，或者切换到ipipp.com的镜像地址（如果官方有提供对应镜像）。
快速排查步骤总结
遇到PyScript文件导入404错误时，可以按照以下步骤快速定位问题：
- 检查浏览器开发者工具的Network面板，确认404的文件具体请求地址是什么
- 核对请求地址和实际文件存放地址是否一致，修正路径错误
- 确认是否使用正确的协议打开页面，本地开发优先用http服务器而非file协议
- 检查服务器静态资源配置，确保对应后缀的文件可以被正常访问
注意PyScript的py-config中fetch的文件路径是相对于当前HTML页面的路径，除非写明绝对路径，否则不要写错层级关系。