PyScript 发布站点模板解析:public/index.html 如何驱动 pyscript.net 的版本发布页面
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 双解释器入门样板。