PPysolate SpineREAD THE CODE · UNDERSTAND THE SYSTEM
课程与章节
CODE READING / 32

启动静态阅读服务

tools/read-local.sh

本章目录

先回答一个问题：make read 成功后，读者实际读到的文件从哪里来？它不是站点构建入口，而是一个很薄的本地预览层：检查 site/dist/index.html 存在，确认有 python3，然后把这个目录绑定到 127.0.0.1 上的 Python 标准库 HTTP server。

make site
  → pnpm build
  → site/dist/
       ↓
make read
  → tools/read-local.sh
  → python3 -m http.server
  → http://127.0.0.1:4328/

make site 负责把 Markdown、路由和资源变成静态文件；make read 只读取这些文件。它不安装 npm 依赖、不运行 Astro、不重编译 Guest，也不下载内容。要更新页面，先生成新的 site/dist，再启动或重新启动阅读器。

1. 脚本怎样定位站点

tools/read-local.sh · L1–L10 · 打开完整源码

#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")/.."
[[ -f site/dist/index.html ]] || { printf 'Missing built site. Prepare dependencies online, then run make site.
' >&2; exit 1; }
command -v python3 >/dev/null || { printf 'python3 is required for the local static preview.
' >&2; exit 1; }
printf 'Local reading: http://127.0.0.1:%s/ (Ctrl-C to stop; no npm download)
' "${PORT:-4328}"
exec python3 -m http.server "${PORT:-4328}" --bind 127.0.0.1 --directory site/dist

脚本用 Bash 严格模式运行，并根据脚本自身路径回到仓库根目录。因此无论调用者当前目录在哪里，site/dist 都指向这个仓库的静态输出。它只检查 site/dist/index.html 是普通文件；这个检查是最小启动条件，不会遍历所有页面和资源，也不会判断文件的生成时间、内容版本或是否与当前源码一致。

首页检查通过后，脚本用 command -v python3 确认本机能找到 Python。缺少首页或 Python 时，在启动服务器前以非零退出。脚本没有 pnpm、npm、curl 或其他下载命令，所以失败时不会自动补齐站点依赖。

2. 端口和进程交接

端口来自 ${PORT:-4328}：变量未设置或为空时使用 4328，否则使用调用者给出的值。这个展开式同时出现在访问提示和服务器命令中，正常情况下两者一致。脚本没有自行检查端口是不是数字或是否在有效范围内；非法值、被占用的端口或 HTTP server 启动失败，会由最后一条命令返回非零。

最后一行用 exec 启动 python3 -m http.server，文档根是 site/dist，绑定地址是 127.0.0.1。exec 用服务器进程替换 Bash 进程，不让包装脚本额外留在前台；服务器结束时，脚本进程也结束。服务器是长时间运行的进程，通常用 Ctrl-C 停止。

127.0.0.1 把访问范围限制为本机回环接口。它和 npm 的离线设置无关，也不是 make offline 的 namespace：这里没有创建隔离网络，只有服务地址没有绑定到 0.0.0.0。因此本地阅读器的任务是提供静态内容，不是证明构建命令或任意网络都被阻断。

3. 旧产物和新源码的边界

只要旧的 site/dist/index.html 仍在，make read 就可能启动，即使它不是当前源码生成的。这是脚本有意保留的窄检查：它确认“有一个站点首页可服务”，不确认“站点刚刚成功构建”。深层页面或资源缺失也不会在启动前被发现，浏览器请求时才可能暴露。

站点构建失败不会由 read 修复；Guest 构建失败也不会影响这个静态服务器是否能继续提供旧目录。相应地，阅读已有站点不能反向证明 make site、make guest 或 make offline 成功。要判断构建状态，应分别查看构建命令的退出结果和离线脚本的最终消息。

4. 读完后应能回答

  1. 为什么 make read 能启动，却不能证明 site/dist 是最新的？
  2. 为什么把绑定地址改成 0.0.0.0 会扩大访问边界？
  3. PORT=0 时提示文本和实际监听端口为什么可能不一致？

这章是工程旁支的终点：先由构建入口选择 site，再由离线检查在 Linux/Ubuntu namespace 中验收构建命令，最后用本地阅读器查看已经生成的静态输出。本章覆盖 tools/read-local.sh 的全部非空源码行，没有启动服务器、占用端口或访问页面，因此没有把当前站点的新旧状态当成已验证事实。