PyScript 发布站点模板解析:public/index.html 如何驱动 pyscript.net 的版本发布页面

原创2026-09-30 23:35:341,418 阅读
文章标签:前端开发工具

PyScript 发布站点模板解析:public/index.html 如何驱动 pyscript.net 的版本发布页面

导读

本文聚焦 PyScript 仓库中 public/ 目录的职责:index.html 是 GitHub Actions 发布流水线的页面模板,用于生成汇聚某次 PyScript 发行版全部信息的静态页(版本号、core 产物、离线包、双解释器示例),最终发布到 pyscript.net 域名。读完本文,你将掌握模板中 _VERSION_、_PATH_、_DOC_VERSION_、_TAG_VERSION_ 四个占位符的含义与替换机制,理解 release / snapshot / unstable 三类发布流程如何复用同一模板,并能自行用 sed 命令复现页面生成过程。

public/ 目录在仓库中的定位

仓库顶层 public/ 目录下只有两个文件:README.md 与 index.html。前者仅用一段话说明用途:该目录下的 index.html 被本仓库 .github/workflows/ 目录中定义的 GitHub Actions 用作静态页模板,用于汇聚某次 PyScript 发行版的所有相关信息;此类静态页(及其关联的发布产物)最终会落在 https://pyscript.net/ 域名下。

也就是说,public/index.html 并不是一个随时可用的独立页面,而是一份带占位符的 HTML 骨架。真正的页面在 CI 流水线执行时,由 sed 命令把占位符替换成具体版本号与资源路径后生成到 core/dist/index.html,再同步到 S3 托管的 pyscript.net 站点。

模板中的四个占位符:含义与替换规则

整个模板的“动态化”全部由四个占位符承担,它们在 public/index.html 中出现的位点与各自用途如下:

占位符 出现位置(模板内) 被替换成的实际值 作用
_VERSION_ <title>、<h1>、导航链接、离线包文件名、示例标题与注释 版本号(如 2022.09.1、latest) 页面上所有展示“当前版本”的文字
_PATH_ core.css 与 core.js 的引用路径 ./ 或 https://pyscript.net/releases/<版本>/ 等 决定产物资源是从相对路径还是 CDN 绝对路径加载
_DOC_VERSION_ Docs 链接 https://docs.pyscript.net/_DOC_VERSION_/ latest 或具体版本号 指向对应版本的在线文档
_TAG_VERSION_ Changes 链接 https://github.com/pyscript/pyscript/releases_TAG_VERSION_ /tag/<版本> 或空字符串 指向该版本对应的 GitHub Release 标签页

在流水线中,替换动作由一条 sed 命令完成,例如 publish-release.yml 中的写法:

sed -e 's#_PATH_#https://pyscript.net/releases/${{ github.ref_name }}/#g' \
    -e 's#_DOC_VERSION_#${{ github.ref_name }}#g' \
    -e 's#_TAG_VERSION_#/tag/${{ github.ref_name }}#g' \
    -e 's#_VERSION_#${{ github.ref_name }}#g' \
    ./public/index.html > ./core/dist/index.html

注意 sed 命令使用 # 作为分隔符(而非默认的 /),因为 _PATH_ 的替换值本身包含斜杠,避免转义地狱。若缺少 -e 尾部,替换默认只作用于每行第一个匹配;其中 _PATH_ 在模板中同时出现在 <link> 与 <script> 两处,因此流水线显式使用了全局替换标志 g(见 publish-release.yml),确保两处都被替换。

模板结构逐段拆解

头部:样式、模块脚本与剪贴板辅助函数

<link rel="stylesheet" href="_PATH_core.css" />
<script type="module" src="_PATH_core.js"></script>
<title>PyScript Release: _VERSION_</title>
  • core.css 提供页面基础样式;core.js 以 ES Module 方式加载,这是 PyScript 运行时在浏览器中的核心入口(构建产物生成规则见 core/rollup/core.config.js,输出目录为 ./dist)。
  • 内嵌 <style> 定义了深色主题(#2d2e35 背景、白色正文、#fda703 橙色链接),并让 #header > svg 中的 Logo 在 400px 以下窄屏时收缩到 256px 宽,保证移动端可读。
  • copyToClipboard() 函数读取 <pre id="example"> 的文本并调用 navigator.clipboard.writeText 写入剪贴板,配合“Example”标题旁的复制按钮使用。

主体:头部横幅与文件清单

<h1>PyScript version: _VERSION_</h1>
<p><a href="https://pyscript.net/">Home</a> | <a href="https://docs.pyscript.net/_DOC_VERSION_/">Docs</a> | <a href="https://github.com/pyscript/pyscript">Code</a> | <a href="https://github.com/pyscript/pyscript/releases_TAG_VERSION_">Changes</a></p>

导航区聚合了官方首页、对应版本文档、源码仓库与版本变更记录。紧随其后的 Files 清单是发布页的核心信息区,列出该版本随附的产物:

  • core.css:运行时样式;
  • core.js:运行时主模块;
  • core.js.map:core.js 的 Source Map,便于线上调试;
  • offline__VERSION_.zip:该版本打包好的离线使用压缩包,页面文案明确标注 "PyScript VERSION zipped up for offline use"。

离线包由 publish-release.yml 中的 npm run build:offline 生成:rollup 侧脚本 core/rollup/offline.cjs 会读取 node_modules/polyscript/versions 下的 pyodide 与 micropython 版本号,生成内含 pyscript/core.js、pyscript/core.css 与两个解释器演示脚本的 offline.html,随后流水线把离线包重命名为带版本号的形式:mv ./dist/offline.zip ./dist/offline_${{ github.ref_name }}.zip。

双解释器版本展示

模板主体放有两个 <script> 块,分别以 type="py"(Pyodide)与 type="mpy"(MicroPython)类型标记,二者都执行相同的两行 Python:

<script type="py">
    from pyscript import display
    import sys
    display(sys.version)
</script>
<script type="mpy">
    from pyscript import display
    import sys
    display(sys.version)
</script>

页面加载时,PyScript 运行时会为每个解释器创建独立执行环境,把 sys.version 渲染进 #out 容器,直观展示两个 Python 解释器的版本。这种“一个页面、双解释器并存”的用法与仓库测试页保持一致(如 core/tests/javascript/ffi.html 等测试页均围绕同一运行时机制),也验证了 display 这一核心 API 在两种解释器下的可用性。

Example 区块:可复制的 Hello World 模板

页面底部的 <pre id="example"> 内嵌一份转义后的完整示例 HTML,其结构如下(去转义后):

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width,initial-scale=1" />
        <title>PyScript _VERSION_</title>
        <link rel="stylesheet" href="_PATH_core.css" />
        <script type="module" src="_PATH_core.js"></script>
    </head>
    <body>
        <h1>Hello world!</h1>
        <p>These are the Python interpreters in PyScript _VERSION_:</p>
        <script type="py">
            # Pyodide
            from pyscript import display
            import sys
            display(sys.version)
        </script>
        <script type="mpy">
            # MicroPython
            from pyscript import display
            import sys
            display(sys.version)
        </script>
    </body>
</html>

这段代码是“最小编程入门页”的样板:仅引入 core.css 与 core.js,即可在浏览器中获得 Python 运行时。读者点击标题旁的复制按钮(copyToClipboard()),即可把这段代码粘贴到本地 HTML 文件中,替换 _PATH_、_VERSION_ 为实际值后直接打开运行。这也是 PyScript 用户在浏览器里体验“双解释器 Hello World”最简路径。

三类发布流水线如何复用同一模板

public/index.html 之所以称为模板,是因为仓库内四份 GitHub Actions 工作流文件都指向它,只是传入的替换值不同:

工作流 触发时机 _PATH_ _DOC_VERSION_ _TAG_VERSION_ _VERSION_ 产物去向
prepare-release.yml 推送 YYYY.MM.MICRO 格式标签 ./ latest 空 latest 打包为 build.zip,创建草稿 Release
publish-release.yml Release 正式发布 https://pyscript.net/releases/<ref>/ <ref> /tag/<ref> <ref> 上传离线包并同步到 S3 的 releases/<ref>/
publish-snapshot.yml 手动触发(workflow_dispatch,输入 snapshot_version) https://pyscript.net/snapshots/<ver>/ <ver> /tag/<ver> <ver> 同步到 S3 的 snapshots/<ver>/
publish-unstable.yml 合并到 main(改动涉及 core/、examples/)或手动触发 ./ latest 空 latest 同步到 S3 的 unstable/

几点细节值得注意:

  • prepare-release 与 publish-unstable 使用相对路径 ./:此时 core.js、core.css 与生成的 index.html 位于同一 dist/ 目录(或随 build.zip 分发),相对路径即可正确解析。
  • release 与 snapshot 使用绝对 CDN 路径:页面被部署到 releases/<版本>/ 或 snapshots/<版本>/ 这类独立目录,资源链接必须指向同域下的绝对路径。
  • Changes 链接只在有正式标签时出现:_TAG_VERSION_ 替换为空后,链接退化为 releases 目录页;_DOC_VERSION_ 替换为 latest 时文档链接指向最新版文档,替换为具体版本号则指向对应版本文档。
  • snapshot 工作流校验版本格式:snapshot_version 的输入说明示例为 2022.09.1 或 2022.09.1.RC1,与 prepare-release 的 tag 正则 <a href="https://link.gitcode.com/i/f158255e8a251f9237b676a0df734439" target="_blank">0-9][0-9][0-9][0-9].[0-9][0-9].[0-9]+([prepare-release.yml)一致,整体遵循 Calendar Versioning(日历版本) 约定。

本地复现:手动生成发布页

无需等待 CI,可在仓库根目录用 sed 复现 release 场景下的页面生成(示意命令,生成到临时目录):

mkdir -p /tmp/pyscript_release
sed -e 's#_PATH_#https://pyscript.net/releases/2026.09.1/#g' \
    -e 's#_DOC_VERSION_#2026.09.1#g' \
    -e 's#_TAG_VERSION_#/tag/2026.09.1#g' \
    -e 's#_VERSION_#2026.09.1#g' \
    ./public/index.html > /tmp/pyscript_release/index.html

生成后检查 index.html 中不再残留 _VERSION_、_PATH_ 等占位符,title 显示为 PyScript Release: 2026.09.1,core.css 链接指向 https://pyscript.net/releases/2026.09.1/core.css。若要把页面当作本地文件直接打开调试,只需把 _PATH_ 替换为 ./ 并放置在同目录的 core.js、core.css 旁边即可。

小结

public/index.html 是 PyScript 发布体系中的关键一环:一份带占位符的静态模板,配合 GitHub Actions 中的 sed 替换,以极低的维护成本支撑起 pyscript.net 上 release、snapshot、unstable 三类页面的生成。理解它的占位符约定,也就掌握了 PyScript 发布产物(core.js、core.css、Source Map 与离线 zip)的组织方式与分发逻辑;而模板内嵌的 Example 代码,本身就是一份可复用的 PyScript 双解释器入门样板。

登录后查看全文
pyscript