这篇文章把 Luomoの云日常本站博客 自己放到解剖台上：源码托管在 GitHub，Hexo 把 Markdown 编译成静态文件，Butterfly 负责页面结构与样式，Vercel 连接 main 分支并将构建结果发布到 blog.luomo.moe。这不是一份只在空目录里成功过的“理论教程”，而是对当前生产仓库、部署记录和几次真实事故的复盘。

先看最终架构

  flowchart LR  A["source/_posts/*.md\n文章与 Front-matter"] --> B["Markdown-it 与内容插件\nKaTeX / Ruby / Hint / Spoiler"]  B --> C["Hexo 7.3.0\n生成路由与静态资源"]  T["Butterfly 4.13.0\nPug + Stylus + Tag Plugins"] --> C  X["自定义 CSS / JS\n白色主题与 PJAX 兼容"] --> C  C --> P["public/\nHTML / CSS / JS / XML"]  P --> V["Vercel Production\n静态托管与边缘缓存"]  G["GitHub main 分支"] --> V  V --> D["blog.luomo.moe\nHTTPS 自定义域名"]  

整条链路里没有运行时数据库，也没有常驻 Node.js 服务。Node.js 只在构建阶段执行 Hexo；部署完成后，访客拿到的是预先生成的 HTML、CSS、JavaScript、图片、搜索索引、Feed 和站点地图。构建时生成 是理解这套架构的三个关键词。

当前生产基线

截至本文发布前，我重新执行了版本检查、干净构建与 Vercel 控制面审计：

仓库结构：哪些文件真正参与部署

1
2
3
4
5
6
7
8
9
10
11
12
13
14

hexo-blog/
├─ _config.yml                    # Hexo 站点、路由与插件配置
├─ package.json                   # 依赖与 clean/build/server 脚本
├─ pnpm-lock.yaml                 # 可复现依赖图
├─ pnpm-workspace.yaml            # 将仓库根声明为 pnpm workspace
├─ vercel.json                    # Vercel 构建、输出与缓存响应头
├─ source/
│  ├─ _posts/                    # 已发布 Markdown 文章
│  ├─ _drafts/                   # 草稿，不进入正式构建
│  ├─ css/luomo-theme.css        # 白色主题覆盖层
│  ├─ js/luomo-theme.js          # 项目筛选与 PJAX 重初始化
│  └─ service-worker.js          # 旧离线缓存的一次性退役脚本
├─ themes/butterfly/              # Butterfly 4.13.0 主题源码
└─ public/                        # 构建产物，忽略提交，由 Vercel 生成

这里最重要的边界是：source/、主题和配置属于源码，public/ 属于可重复生成的产物。仓库的 .gitignore 会排除 public/、node_modules/、db.json、.vercel/ 与本地环境文件，避免把几万份可再生文件和项目链接元数据一起扔进 Git。

从零准备运行环境

为了避开即将退役的 Node.js 20，新部署建议直接使用 Node.js 24 LTS，并通过 Corepack 或独立安装获得 pnpm：

1
2
3
4

node --version
corepack enable
corepack prepare pnpm@11.9.0 --activate
pnpm --version

然后克隆仓库并严格按照锁文件安装：

1
2
3

git clone https://github.com/luomo66ccff/hexo.git
cd hexo
pnpm install --frozen-lockfile

--frozen-lockfile 会在 package.json 与锁文件不一致时直接失败。失败虽然很不给面子，却比生产构建偷偷换一批依赖、上线后集体失忆更安全。

pnpm 版本还有一个现实差异

仓库的 packageManager 声明为 pnpm@11.9.0，当前本地验证实际使用 11.16.0；现有 Vercel 项目则根据项目创建时间和锁文件格式选择了 pnpm 9.x。也就是说，“写了 packageManager”不自动等于每个环境都精确执行该版本。

若团队需要完全一致，可以启用 Vercel 支持的 Corepack 机制，并把本地、CI 与 Vercel 的 pnpm 版本统一；在完成迁移前，至少要保留锁文件安装和 Preview 验证，不能一边跨大版本一边直冲生产。

package.json：把流程收口成四个命令

仓库使用的脚本非常克制：

1
2
3
4
5
6
7
8

{
  "scripts": {
    "build": "hexo generate",
    "clean": "hexo clean",
    "deploy": "hexo deploy",
    "server": "hexo server"
  }
}

日常真正使用的是：

1
2
3

pnpm run clean     # 删除 db.json 与 public，排除旧产物污染
pnpm run build     # 生成 public
pnpm run server    # 在 http://localhost:4000 预览

虽然还保留了 hexo deploy 脚本，但本站生产链路并不依赖它。仓库也没有安装 hexo-deployer-git，所以正确发布方式是提交源码并推送 GitHub，再由 Vercel 构建；不要把 hexo deploy 和 Vercel Git 集成同时当作两位司机抢方向盘。

为什么需要 pnpm-workspace.yaml

当前文件内容如下：

1
2
3
4
5
6
7
8

packages:
  - .

allowBuilds:
  core-js: true
  ejs: true
  hexo-util: true
  highlight.js: true

packages: - . 明确告诉 pnpm：仓库根就是工作区包。它看起来像在认真声明“我家住我家”，但这行曾经解决过 Vercel 对工作区根识别不完整的问题。allowBuilds 则只允许列出的依赖执行构建脚本，降低安装阶段随意运行脚本的范围。

pnpm 官方工作区文档要求工作区根包含 pnpm-workspace.yaml。即使这里只有一个包，把根目录显式列出也能让本地与远端对项目边界形成同一套认知。

Hexo 主配置：域名、路由与生成目录

_config.yml 中与部署最相关的部分可以压缩为：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

title: Luomoの云日常
language: zh-CN
timezone: Asia/Shanghai

url: https://blog.luomo.moe
permalink: posts/:abbrlink.html
source_dir: source
public_dir: public
render_drafts: false
theme: butterfly

markdown:
  plugins:
    - '@renbaoshuo/markdown-it-katex'
    - markdown-it-ruby

url 必须写正式域名，否则 Feed、站点地图、规范链接和百度提交列表可能继续散发旧地址。permalink 使用 hexo-abbrlink 生成稳定短链接，标题改名时不会顺手给所有外链来一记背刺。

草稿放在 source/_drafts/，因为 render_drafts: false，正式构建不会发布；需要预览时使用 hexo server --draft，不要为了看草稿把它先塞进 _posts 再祈祷自己记得删。

我扫描到的 28 个直接依赖

依赖多不代表每篇文章都要全员上台。下面按职责列出当前安装结果，版本来自实际依赖树：

全站构建时，搜索、Feed、站点地图、nofollow 与字数统计会自然参与；本文另外使用了 KaTeX、Ruby、Hint、Spoiler，以及 Butterfly 自带的 Mermaid、Note、Tabs、Timeline、Button、Label 和 HideToggle。APlayer 与 Bilibili 不服务于部署主题，硬塞一段音乐视频只会让教程像项目经理突然唱起片尾曲。

Butterfly 与白色主题如何叠加

本站把 Butterfly 4.13.0 的源码放在 themes/butterfly/ 中，并启用了这些关键项：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

display_mode: light

darkmode:
  enable: false
  button: false

preloader:
  enable: false

wordcount:
  enable: true

search:
  use: local_search

pjax:
  enable: true

lazyload:
  enable: true

mermaid:
  enable: true

自定义样式不直接堆进文章，而是由主题注入：

1
2
3
4
5

inject:
  head:
    - <link rel="stylesheet" href="/css/luomo-theme.css?v=20260804-white">
  bottom:
    - <script src="/js/luomo-theme.js?v=20260626-butterfly"></script>

source/css/luomo-theme.css 将正文卡片、表格、代码块、导航和页脚统一为白色；移动端表格单独允许横向滚动。source/js/luomo-theme.js 在 DOMContentLoaded 和 pjax:complete 后重新初始化交互，避免 PJAX 换页后按钮看得见却像灵魂已离职。

长期维护时，优先把个性化放在 source/css、source/js 和独立主题配置中。本站历史上修改过少量 Butterfly 内部模板与过滤器，所以升级主题前必须对比这些补丁，不能直接覆盖整个主题目录。

vercel.json：生产构建的唯一明确契约

当前仓库使用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "buildCommand": "pnpm run build",
  "installCommand": "pnpm install --frozen-lockfile",
  "outputDirectory": "public",
  "framework": "hexo",
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=0, s-maxage=300, must-revalidate"
        }
      ]
    }
  ]
}

四个核心字段各管一层：

控制台的 Project Inspect 可能显示框架默认命令，但仓库中的显式配置会进入实际构建。判断最终执行了什么要看部署日志；本站生产日志确实运行了 pnpm install --frozen-lockfile 与 pnpm run build。

缓存头为什么这样写

max-age=0 要求浏览器重新验证，s-maxage=300 允许共享边缘缓存保留 300 秒，must-revalidate 避免过期内容被随意继续使用。它适合更新频率不高的静态博客，同时降低长时间卡住旧 HTML 的概率。

一次发布的体感时间可以近似拆成：

$$T_{visible} \approx T_{install} + T_{generate} + T_{upload} + T_{alias}$$

边缘缓存与 DNS 状态会影响个别访问，但 Vercel 的部署本身是独立产物，Production 就绪后再把域名别名切过去。不要在构建还红着时把“CDN 有缓存”当作电子护身符。

在 Vercel 导入 GitHub 仓库

1. 导入仓库

进入 Vercel Dashboard，选择 Add New → Project，授权 GitHub 后导入 luomo66ccff/hexo。本站控制面当前确认的绑定关系是：

因为仓库已有 vercel.json，不必在控制台重复维护三套命令。若控制台有旧的手工覆盖值，要么清空让仓库配置接管，要么确保两边完全一致；最怕一边改成 pnpm，另一边还在召唤 npm，最后构建日志现场举行包管理器武林大会。

2. 理解 Preview 与 Production

Vercel 的 Git 集成会为非生产分支和 Pull Request 创建 Preview，main 则跟踪 Production。推荐流程是：

本地发布命令

1
2
3
4

pnpm install --frozen-lockfile
pnpm run clean
pnpm run build
pnpm run server

浏览器检查完成后：

1
2
3
4
5

git status --short
git diff --check
git add source/_posts/your-post.md
git commit -m "docs: 发布 Hexo 部署教程"
git push origin main

推送 main 后，Git 集成会自动创建 Production 部署。Vercel Git 部署文档也说明非生产分支和 Pull Request 会获得独立 Preview，生产分支则生成 Production。

CLI 发布与排障备用路线

Git 自动部署是日常主路，CLI 是手动发布、检查和回滚的备用通道：

1
2
3
4
5
6
7
8
9
10

npx vercel login
npx vercel link
npx vercel project inspect hexo
npx vercel list hexo --status READY

# Preview
npx vercel deploy

# 明确发布 Production
npx vercel deploy --prod

vercel link 会创建 .vercel/project.json，其中是项目与组织标识，不是部署源码；本站将整个 .vercel/ 加入 .gitignore。自动化环境中的令牌必须放在 Secret 或环境变量中，禁止写进命令历史和仓库。

1
2

npx vercel inspect <deployment-url>
npx vercel logs <deployment-url> --level error --since 1h

1
2
3

npx vercel rollback
# 或指定一份已知正常的部署
npx vercel rollback <deployment-url-or-id>

1
2
3

npx vercel pull --yes --environment=production
npx vercel build --prod
npx vercel deploy --prebuilt --prod

绑定 blog.luomo.moe

在 Vercel 项目的 Settings → Domains 添加 blog.luomo.moe。这是子域名，通常需要在 DNS 服务商处添加 Vercel 当时显示的 CNAME 目标。

不要从旧教程里复制某个固定 CNAME 值。Vercel 自定义域名文档要求以项目面板显示的 DNS 目标为准；域名被其他账号占用时还可能要求 TXT 验证。DNS 验证成功后，Vercel 会自动申请 HTTPS 证书。

站点配置也必须同步：

1
2

# _config.yml
url: https://blog.luomo.moe

还要检查 source/robots.txt、Feed、Sitemap、Open Graph、评论系统白名单和第三方回调地址。只改浏览器地址栏能访问，不代表整站的机器读者已经跟着搬家。

四次真实踩坑复盘

坑一：Vercel 识别 pnpm 工作区不稳定

早期仓库只有 allowBuilds，没有 packages。加入下面两行后，仓库根被明确识别为工作区包：

1
2

packages:
  - .

同时将 .vercel/ 和 .env.local 排除提交。修复重点不是“多写一份 YAML”，而是让本地 pnpm、Vercel 安装阶段和项目根目录对同一边界达成一致。

坑二：页面黑屏和文章排版错位

这次故障由多件小事叠加：

1. 自定义 CSS 使用了 .article-container，而实际正文节点是 #article-container；
2. 全屏预加载器让异常加载表现成整页遮罩；
3. 文章头图与全站图片懒加载规则发生重复处理；
4. 表格在手机端没有自己的横向滚动容器；
5. Note 标签参数与当前 Butterfly 版本语法不一致。

修复后关闭全屏预加载器、改正选择器、让带 nolazyload 的图片绕过过滤器，并为表格添加移动端滚动。“把背景改白”只能遮住部分症状，真正的黑屏还可能来自覆盖层、缓存和资源加载。

坑三：主题配置是 light，视觉却仍然很黑

display_mode: light 只决定 Butterfly 默认模式，旧自定义 CSS 仍可用深色变量把整站重新涂黑。因此白色主题迁移同时修改了：

• 页面背景与玻璃卡片变量；
• 导航、正文、标题和页脚文字色；
• 代码块、表格、引用与 Note；
• 前后文章导航；
• 移动端正文内边距与表格滚动；
• 禁用自动暗色模式与暗色切换按钮。

验证主题不能只检查 data-theme="light"，还要读取最终计算样式，并在真实尺寸截图中确认正文背景和文字对比度。

坑四：插件删了，旧 Service Worker 还活着

移除 hexo-offline 只会阻止新构建继续生成缓存逻辑，已经注册在访客浏览器里的 Service Worker 不会自动原地圆寂。它仍可能把旧 HTML、CSS 和脚本塞回来，让生产站出现“代码已经改了，浏览器坚持活在前朝”的现象。

本站使用一次性迁移 Worker：安装后接管页面、删除旧 Cache Storage、注销自身，再让页面重新导航。vercel.json 对 /service-worker.js 单独发送 no-store, no-cache, must-revalidate，确保浏览器能够拿到退役脚本，而不是继续缓存旧 Worker。

构建产物应该验收什么

一次干净构建不是只看退出码为 0。本文写作前的基线构建生成 69 个文件，其中 30 个为 HTML；新增文章后还要检查以下内容：

1
2
3
4
5
6
7

public/posts/<abbrlink>.html     新文章页面
public/index.html                首页收录
public/search.json               本地搜索索引
public/atom.xml                  Atom Feed
public/sitemap.xml               通用站点地图
public/baidusitemap.xml          百度站点地图
public/baidu_urls.txt            最新链接列表

hexo-baidu-url-submit 在公开仓库中只保留生成配置，真实 Token 必须通过私有配置或环境变量提供。看到 baidu_urls.txt 生成，不等于已经向百度成功提交；二者不能用一个绿色日志互相冒充。

桌面端与手机端视觉 QA

生产发布后的判断顺序

1. Vercel 部署是否从 Building 进入 Ready；
2. 部署关联的 Git 提交 SHA 是否与远端 main 一致；
3. 构建日志是否生成目标文章；
4. Production 域名是否已经指向该部署；
5. 若页面异常，先区分构建失败、域名未切换、边缘缓存和浏览器 Service Worker；
6. 问题影响全站时先回滚，再慢慢写事故文学。

Vercel 每次部署都有独立 URL。Preview 没问题但正式域名异常时，不要立刻重写 Hexo；先检查 Production alias、DNS 与缓存层，避免对着正确代码进行错误手术。

还需要继续收紧的地方

最后的复盘

这套博客的部署价值不在于“Vercel 点一下就上线”，而在于把内容、渲染、主题、生成、版本控制和托管边界拆得足够清楚。Markdown 是源，public/ 是产物，GitHub 是版本事实，Vercel Deployment 是不可变发布单元，自定义域名只负责把访客带到已经通过验证的生产版本。

真正让站点稳定的也不是某个神奇插件，而是锁文件、干净构建、Preview、移动端 QA、缓存认知和可回滚发布。把这些步骤做实，写完文章推一次 main 就能优雅上线；把它们跳过，三分钟部署也可能附赠三小时“为什么我这还是黑的”。

这次我选择拆解 HotAPI热榜接口部署仓。它不是我原创的一整套爬虫内核，而是我在 GitHub 上维护、交给 Vercel 托管的部署适配项目：上游核心来自 imsyy/DailyHotApi，遵循 MIT 协议；我的工作重点是把 npm 包固定成可复现依赖，再用极薄的 Node.js 入口与 vercel.json 把它变成公开 Serverless API。

为什么一个三行入口仍然值得写

项目入口只有三行：

1
2
3

import serveHotApi from "dailyhot-api";

serveHotApi();

三行不等于没有架构。它把职责切得很清楚：上游包负责 Hono 路由、数据抓取、格式归一化、JSON/RSS 输出和缓存；部署仓负责版本锁定、ESM 入口、Vercel Function 构建、全路径转发与 GitHub 更新入口。薄部署仓 的目标正是少写重复代码，而不是少做验证。

截至本文审计时，Vercel 项目 hotapi 的生产部署状态为 Ready，构建结果是一枚位于 iad1 的 Node.js Function，解包前显示约 939.08 KB。GitHub 仓库的锁文件固定了 dailyhot-api 2.0.6；上游已经发布 2.0.8，所以“生产正在跑什么”和“上游最新是什么”必须分开记录。

仓库虽小，边界要完整

1
2
3
4
5
6
7
8

hotapi/
├─ index.js                 # Serverless 入口
├─ package.json             # ESM、依赖与脚本
├─ package-lock.json        # 可复现安装契约
├─ vercel.json              # Function 构建与全路径路由
├─ public/                  # 图标等静态资源
└─ .github/
   └─ dependabot.yml        # 每日检查 npm 版本更新

package.json 中有三个不能随手删的关键点：

Vercel 官方文档也明确：无框架 JavaScript Function 若使用 ESM，需要在 package.json 设置 "type": "module"，或者改用 .mjs。这里选择前者，入口文件保持普通 .js 即可。

请求是怎样穿过这三层的

  flowchart LR  U["浏览器 / RSS 阅读器 / 脚本"] --> V["Vercel 路由层"]  V --> F["Node.js Function\nindex.js"]  F --> H["dailyhot-api\nHono 应用"]  H --> R["动态路由注册表"]  R --> S["公开数据源 / RSS / 页面"]  R --> C["NodeCache\n实例内缓存"]  H --> J["JSON 响应"]  H --> X["RSS XML 响应"]  

动态路由为什么比手写 40 次更稳

上游的注册器扫描路由目录，为每个文件创建 /<route> 入口，并在请求时动态导入对应实现。逻辑可以压缩成下面这段伪代码：

1
2
3
4
5
6
7
8
9
10
11

for (const route of routeFiles) {
  app.get(`/${route}`, async (context) => {
    const noCache = context.req.query("cache") === "false";
    const limit = Number(context.req.query("limit"));
    const rss = context.req.query("rss") === "true";

    const { handleRoute } = await import(`./routes/${route}.js`);
    const result = await handleRoute(context, noCache);
    return rss ? toRss(result) : context.json(trim(result, limit));
  });
}

这样新增一个榜单通常只需新增一个路由文件，不必再修改总入口。/all 还能返回路由目录，前端或监控脚本不需要把列表硬编码到自己的版本里。

常用请求如下：

1
2
3
4
5
6
7
8
9
10
11

# 查看可用接口
curl --fail https://hotapi-ten.vercel.app/all

# 只取前 10 条
curl --fail "https://hotapi-ten.vercel.app/bilibili?limit=10"

# 输出 RSS
curl --fail "https://hotapi-ten.vercel.app/zhihu?rss=true"

# 绕过缓存，仅用于排障或人工刷新
curl --fail "https://hotapi-ten.vercel.app/36kr?cache=false"

缓存：Serverless 最容易被误解的一层

上游 2.0.6 默认使用 NodeCache，TTL 是 3600 秒。单进程常驻服务器上，理想情况下同一路由每小时只回源一次；但 Vercel 会冷启动、并发扩容，也可能同时存在多个 Function 实例。各实例内存不共享，因此更准确的近似是：

$$R_{origin} \approx \frac{I_{warm} + I_{cold}}{T_{TTL}}$$

其中 $I_{warm}$ 是窗口内实际承接请求的暖实例数，$I_{cold}$ 是发生冷启动的实例数，$T_{TTL}$ 是缓存秒数。这个公式不是计费器，而是在提醒我们：进程内缓存只能减少单实例回源，不能承诺全局每小时一次。

如果流量上升，需要跨实例稳定缓存，应升级到支持 Redis 的上游版本并接入兼容服务，或者把适合缓存的响应交给 CDN；同时必须遵守数据源更新频率和使用条款，不能用“我有缓存”给高频抓取穿隐身衣。

vercel.json 到底做了什么

仓库当前配置使用显式构建器：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "version": 2,
  "builds": [
    {
      "src": "index.js",
      "use": "@vercel/node"
    }
  ],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "/"
    }
  ]
}

第一段把 index.js 编译为 Node.js Function；第二段把所有访问路径送进同一个 Hono 应用，让 /all、/bilibili、/zhihu 不必各自创建 Function 文件。Vercel 目前仍支持 routes，但官方建议普通重写和响应头优先使用更高层的 rewrites、headers 配置。这个仓库的显式 Function 适配属于需要先做回归验证再迁移的情况，不要只因为新语法看起来更潮就闭眼改配置。

当前 CORS 配置需要收紧

原仓库在 Vercel 路由层同时声明了：

1
2

Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *

浏览器的凭据型 CORS 不接受通配来源；而热榜 API 本身通常只需要公开的 GET 与预检 OPTIONS，也没必要默认放行 PATCH、DELETE、POST、PUT。更稳妥的原则是二选一：

1. 公开只读 API：允许 Origin: *，移除 credentials，只开放 GET, OPTIONS；
2. 私有前端 API：把 Origin 写成明确域名，保留 credentials，并补上 Vary: Origin。

上游 Hono 应用本身已经有 CORS 中间件，部署层不应再发一套互相打架的头。正式上线前应统一到一个地方管理，并用浏览器预检请求验证，而不是让两层 CORS 像两位保安互相检查工作证。

从 GitHub 部署到 Vercel

下面给出一条可复现、可回滚的部署路线。仓库当前生产项目使用 Node.js 22；上游 2.0.6 要求 Node.js 20 或更高版本。

1. 拉取代码并锁定安装

1
2
3
4

git clone https://github.com/luomo66ccff/hotapi.git
cd hotapi
node --version
npm ci

这里用 npm ci，不使用 npm install。前者严格读取 package-lock.json，确保部署复现 2.0.6；后者可能因为 ^2.0.6 自动解析到新的兼容版本，让“重新部署”偷偷变成“顺便升级”。

2. 本地用 Vercel 运行时验证

这个部署仓没有普通 dev 脚本，最接近生产路径的方式是：

1

npx vercel dev

另开终端做四个冒烟测试：

1
2
3
4

curl --fail http://localhost:3000/all
curl --fail "http://localhost:3000/bilibili?limit=3"
curl --fail "http://localhost:3000/zhihu?rss=true"
curl -i -X POST http://localhost:3000/bilibili

预期分别是：路由目录、三条 JSON 数据、XML 响应，以及不支持方法的 405。某个数据源失败不必立刻判定整站坏掉；先用 /all 区分运行时故障与单路由上游变化。

3. 导入 GitHub 仓库

在 Vercel 控制台选择 Add New → Project，导入 luomo66ccff/hotapi。设置如下：

也可以用 CLI：

1
2
3

npx vercel link
npx vercel deploy
npx vercel deploy --prod

第一次先发布 Preview，完成接口检查后再发 Production。GitHub 连接建立后，分支或 Pull Request 生成预览部署，main 进入生产；这样依赖升级不会直接在正式接口上玩俄罗斯轮盘。

4. 环境变量建议

默认配置可以启动，但公开服务建议显式记录这些值：

1
2
3
4
5
6

CACHE_TTL=3600
DISALLOW_ROBOT=true
RSS_MODE=false
USE_LOG_FILE=false
ALLOWED_HOST=your-frontend.example
ALLOWED_DOMAIN=https://your-frontend.example

USE_LOG_FILE=false 很重要：Vercel Function 的本地文件系统不是持久日志盘，运行日志应写到标准输出，再由 Vercel Logs 收集。

5. 发布后的验收

1
2
3

curl --fail https://your-project.vercel.app/all
curl --fail "https://your-project.vercel.app/bilibili?limit=3"
curl -I "https://your-project.vercel.app/zhihu?rss=true"

1
2

npx vercel inspect https://your-project.vercel.app
npx vercel logs https://your-project.vercel.app --since 1h

1
2
3

curl -i -X OPTIONS https://your-project.vercel.app/bilibili \
  -H "Origin: https://your-frontend.example" \
  -H "Access-Control-Request-Method: GET"

6. 绑定域名与回滚

在 Vercel 的 Domains 中添加 API 子域名，再按控制台给出的 DNS 目标配置。不要凭记忆硬写 CNAME；同一个域名若已经被其他项目占用，应先确认归属，避免为了一个热榜接口把主站 DNS 拔成盆栽。

每次更新前保留上一个 Ready 部署。新版本出现系统性 500 时，优先在 Vercel 控制台把别名切回上一份通过验收的生产部署，再分析依赖或数据源变化；不要在事故现场边改 package-lock.json 边许愿。

依赖升级：把“每天检查”变成真正的门禁

仓库已启用 Dependabot，每天检查 npm 依赖。但自动开 PR 不等于自动安全升级，尤其 dailyhot-api 同时包含路由、爬取器、缓存和页面解析逻辑。建议每个升级 PR 至少执行：

1. 锁文件差异审查，确认没有意外主版本跳跃；
2. npx vercel dev 本地启动；
3. /all、一个 JSON 路由、一个 RSS 路由和一个错误方法测试；
4. Preview 部署检查 Function 体积和冷启动；
5. CORS、缓存参数与 robots 行为回归；
6. 只在 Preview 全绿后合并到 main。

从 2.0.6 升到 2.0.8 时，建议把依赖改为精确版本，避免以后无审查漂移：

1
2

npm install --save-exact dailyhot-api@2.0.8
npx vercel dev

验证完再提交 package.json 与 package-lock.json。若希望继续自动接收补丁版本，也可以保留 caret，但生产部署仍必须使用锁文件安装。

公开 API 还缺哪些生产护栏

当前部署适合个人项目、开发测试和轻量聚合，但不能因为 Vercel 自动扩容就假装它无限抗打。

最后的复盘

HotAPI 最值得复用的不是那句 serveHotApi()，而是“核心能力做成包，平台差异留在薄适配层”的思路。业务路由不必知道自己跑在 Vercel，部署仓也不复制 40 份抓取实现；两边通过版本、入口和 HTTP 契约连接。

但薄并不等于随便。真正决定它能否长期运行的是锁文件、Serverless 缓存认知、CORS 边界、Preview 门禁、日志和回滚。把这些补齐，三行代码可以是一座稳稳的桥；忽略它们，三行代码也能是一块写着“此路不通”的电子牌。