4 步跑通 PyScript 配置与部署：从 make setup 到静态托管的实战清单

4 步跑通 PyScript 配置与部署从 make setup 到静态托管的实战清单【免费下载链接】pyscriptAn open source platform for Python in the browser. https://pyscript.net Docs: https://docs.pyscript.net/ Try it: https://pyscript.com/ Community: https://discord.gg/HxvBtukrg2项目地址: https://gitcode.com/gh_mirrors/py/pyscript这一篇是维护 PyScript 期间积累的配置部署笔记覆盖本地构建、py-config三种写法的冲突规则、用事件链定位加载卡点、Worker 配置三要素、静态托管上线时的响应头要求以及上线前该查什么。假设你会 git 和 npm不需要先读懂 polyscript 的启动逻辑。1 环境准备先构建出 core/dist 运行时这一节帮你解决「本地没有可测试的 PyScript 构建产物」的问题。node 20、npm 6、Python 3.8版本不达标make setup会直接报红拒绝安装仓库根目录执行make setup检查版本后执行cd core npm ci并在已激活的 venv/conda 环境里装 requirements.txtblack、pre-commit 等工具链make build在 core 下跑 playwright chromium 安装加完整构建产物落在core/dist/PyScript 页面只依赖两份产物core.css和core.jshead里引用完正文用script typepyPyodide或script typempyMicroPython就能跑 Python。这里有个坑构建会重新生成src/stdlib/pyscript.js把src/stdlib/pyscript/里全部 Python 内嵌成一个 JS 对象和插件入口文件带// ⚠️ This file is an artifact: DO NOT MODIFY头的文件改了一定被覆盖机制见 core/README.md。日常调试别跑完整 build用npm run devchokidar 监听core/src/只重建 stdlib、plugins 和 core 且不压缩改完几秒内生效npm run server则起一个带正确响应头的静态服务器测试页在http://localhost:8080/tests/。2 配置体系一个页面只允许一份全局配置这一节帮你解决「配了 packages 却没生效」这类问题——多半是配置本身被判定为冲突根本没被解析。解析入口在 core/src/config.js规则可以背下来全局配置二选一py-config标签或给script typepy config...加config属性两者同时出现抛CONFLICTING_CODEAmbiguous py-config VS config attribute标签只能有一个多个同样抛错Too many py-config多个脚本带config属性时必须指向同一个文件否则报 Unable to use different configs on main配置内容支持内联或文件 URL格式按扩展名判断.json走 JSON、.toml走 TOML也可用type属性强制。常见键packages [numpy]装哪些包远程自定义包需另开experimental_remote_packages truefiles路径映射把本地文件拷进虚拟文件系统VFS如./src - ./runtime见 config.json 示例plugins [!error]!前缀关闭内置插件错误页示例 就是用它放行 stderrexperimental_ffi_timeout 100调整 Python 调 JS 的超时单位毫秒写自己的 config.toml 时建议照抄仓库测试目录里的最小写法先跑通再改别一上来堆键。3 调试方法事件链定位加载卡点这一节帮你解决「页面白屏不知道卡在哪一步」。PyScript 把生命周期暴露成 DOM 事件py:progressdetail 是Loading xxx/Loaded xxx加载阶段可配合console.time计时、每个脚本的py:done、以及 all-done.js 在所有脚本就绪后派发的py:all-done。测试页里的监听代码可以直接抄script addEventListener(py:progress, ({ detail }) console.log(detail)); addEventListener(py:all-done, () console.log(all scripts ready)); /script再开 DevTools 的 Console 和 NetworkPython 报错、fetch 失败基本无所遁形。想关掉页面上的红色错误卡片比如演示环境不想暴露堆栈就用第 2 节说的plugins [!error]而不是删控制台输出。4 Worker 配置三要素type、config、files这一节帮你解决「主线程被算爆、页面掉帧」的问题。先说结论主线程单次阻塞超过 200ms 掉帧CPU 密集活必须挪进 Web Worker。写法上给script typepy worker加worker属性或在主线程脚本里用PyWorker显式建一个注意PyWorker 只能在主线程创建worker 内部会抛NotSupportedfrom pyscript import PyWorker worker PyWorker(./worker.py, typepyodide, config./config.json) await worker.ready这就是三要素type定解释器pyodide全量 CPython、micropython轻量版config复用第 2 节那套体系给 worker 单独配packagesfiles把 worker 要用的.py映射进它的 VFS参考 worker 测试。这里有个坑worker 里代理window/document依赖 SharedArrayBuffer它要求响应带 COOP/COEP 头。头缺失时 worker 内pyscript.window是NotSupported占位如果本就不需要碰 DOM配sync_main_only true可消掉那条警告no_sab 示例 演示了这条路径。5 生产部署静态托管 两个响应头这一节帮你解决「本地能跑上线后 worker 全挂」的问题。PyScript 应用是纯静态站点Nginx、Netlify、Vercel 都行托管core/dist加你的页面即可。但有两个响应头必须在服务器上配好本地npm run serverstatic-handler --coi和make servemini-coi替你做了这件事仓库里 mini-coi.js 能看到具体值Cross-Origin-Opener-Policy: same-originCross-Origin-Embedder-Policy: require-corp缺了这俩第 4 节的 worker DOM 代理就不可用用了 COEP 后页面里所有跨域资源都得带 CORP 标记第三方资源没配会整页加载失败这是最常见的上线事故。上线前检查清单make build全绿它会先跑 pre-commit 和 oxlint收尾自动执行 playwright 集成测试JS 测试加 Python 测试在 mpy/py 双解释器、主线程/worker 四种组合下各跑一遍dist/core.js、dist/core.css的相对路径引用无误页面监听py:all-done做加载完成的最终确认别只信py:ready想压体积用npm run size看 dist 各文件的 brotli 大小再精简packages6 踩坑回查表与扩展方向这一节帮你解决「上线一周后偶发报错」的反查效率问题。控制台出现CONFLICTING_CODE/BAD_CONFIG回第 2 节对照标签与config属性是否混用包装不上先核对packages拼写和可达性装远程自定义包确认experimental_remote_packages已开远程包示例 给了完整形态worker 里pyscript.window抛NotSupportedSharedArrayBuffer 不可用检查响应头或改走sync通道、配sync_main_only truePython 调 JS 卡死给experimental_ffi_timeout设一个明确的毫秒上限让它可预期地抛错而不是无限挂起扩展方向是插件内置插件在 core/src/plugins/新建插件只要加一个入口文件构建器会按名字在 dist 里产出独立 chunk不增大core.js体积第三方插件不用进仓库页面里import pyscript/core后动态加载即可py-editor、py-terminal、py-game都是现成参照。收尾给你下一步把第 2 节的 TOML 写进自己的项目make build全绿后用第 3 节的事件监听确认一次完整加载链路再对照第 5 节清单把响应头加到服务器上。【免费下载链接】pyscriptAn open source platform for Python in the browser. https://pyscript.net Docs: https://docs.pyscript.net/ Try it: https://pyscript.com/ Community: https://discord.gg/HxvBtukrg2项目地址: https://gitcode.com/gh_mirrors/py/pyscript创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考