解决 Vercel 部署 Node.js 版本过期问题（18.x → 22.x）

技术运维 , , , 评论

问题背景

今天在使用 Vercel CLI 部署 Hexo 博客时，遇到了一个 Node.js 版本兼容性问题：

1
Error: Node.js Version "18.x" is discontinued and must be upgraded. Please set Node.js Version to 22.x in your Project Settings to use Node.js 22.

这说明 Vercel 已经停止支持 Node.js 18.x 版本，需要升级到 22.x。

问题分析

Vercel 平台会定期更新其支持的 Node.js 版本，当某个版本被标记为 “discontinued”（已停止支持）时，就必须升级到更新的版本。这是一个常见的云平台维护操作。

解决方案

方案一：通过 Vercel Dashboard（推荐）

这是最直接和可靠的解决方法：

  1. 访问 Vercel 项目 Dashboard：https://vercel.com/gggwbs-projects/gggwb-github-io
  2. 进入项目 Settings（设置）
  3. 找到 Build & Development Settings（构建和开发设置）
  4. 将 Node.js Version 从 “18.x” 改为 “22.x”
  5. 保存设置并重新部署

方案二：通过配置文件

虽然主要通过 Dashboard 设置，但也可以在项目中添加相关配置文件作为最佳实践：

1. 创建 .nvmrc 文件

在项目根目录创建 .nvmrc 文件指定 Node.js 版本：

1
echo "22" > .nvmrc

2. 更新 vercel.json 配置

在 vercel.json 中添加 Node.js 环境变量：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "public": true,
  "routes": [
    {
      "src": "/(.*)",
      "dest": "public/$1"
    }
  ],
  "alias": "blog.gwbiao.eu.org",
  "buildCommand": "npm run build",
  "outputDirectory": "public",
  "build": {
    "env": {
      "NODE_VERSION": "22.x"
    }
  }
}

操作步骤

1. 检查当前项目

1
2
cd /Users/gggwb/Documents/gggwb.github.io
ls -la | grep vercel

2. 更新配置文件

1
2
3
4
# 创建 .nvmrc 文件
echo "22" > .nvmrc

# 更新 vercel.json（已配置好）

3. 提交更改

1
2
3
4
5
6
7
8
9
git add .nvmrc vercel.json
git commit -m "Upgrade Node.js version to 22.x for Vercel deployment

- Add .nvmrc file to specify Node.js 22
- Update vercel.json with Node.js environment variable

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>"

4. 重新部署

1
vercel --prod

遇到的额外问题：Hexo 主题兼容性

在 Node.js 版本升级后，还遇到了 Hexo 7.0.0 主题模板的兼容性问题。

问题现象

执行 hexo g 命令时出现错误：

1
2
3
4
5
6
7
8
9
TypeError: /Users/gggwb/Documents/gggwb.github.io/themes/pure/layout/_partial/post/category.ejs:4
    <%- list_categories(post.categories, {
      show_count: false,
      class: 'article-category',
      style: 'none',
      separator: '►'
    }) %>

object is not a function

以及类似的 list_tags 函数错误：

1
2
3
4
5
6
7
8
TypeError: /Users/gggwb/Documents/gggwb.github.io/themes/pure/layout/_partial/post/tag.ejs:4
    <%- list_tags(post.tags, {
       show_count: false,
       style: 'link',
       class: 'article-tag'
    }) %>

tags.toArray is not a function

问题分析

这是 Hexo 7.0.0 版本与 Node.js 22.x 升级后的兼容性问题：

  1. API 参数格式要求：list_categories 和 list_tags 辅助函数在 Node.js 22.x 环境下对参数格式要求更严格
  2. 错误的参数格式：将参数包装在对象中会导致显示全站所有的分类和标签，而不是当前文章的分类和标签

解决方案

重要提示：正确的格式是保持原有的参数格式，即将文章的分类/标签作为第一个参数，选项作为第二个参数。

1. 修复分类模板

文件位置：themes/pure/layout/_partial/post/category.ejs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<!-- 正确的格式（保持原有格式） -->
<% if (post.categories && post.categories.length){ %>
  <span class="article-category">
    <i class="icon icon-folder"></i>
    <%- list_categories(post.categories, {
      show_count: false,
      class: 'article-category',
      style: 'none',
      separator: '►'
    }) %>
  </span>
<% } %>

<!-- ❌ 错误的格式（会导致显示全部分类） -->
<% if (post.categories && post.categories.length){ %>
  <span class="article-category">
    <i class="icon icon-folder"></i>
    <%- list_categories({
      categories: post.categories,
      show_count: false,
      class: 'article-category',
      style: 'none',
      separator: '►'
    }) %>
  </span>
<% } %>

2. 修复标签模板

文件位置：themes/pure/layout/_partial/post/tag.ejs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<!-- 正确的格式（保持原有格式） -->
<% if (post.tags && post.tags.length){ %>
  <span class="article-tag">
    <i class="icon icon-tags"></i>
    <%- list_tags(post.tags, {
      show_count: false,
      style: 'link',
      class: 'article-tag'
    }) %>
  </span>
<% } %>

<!-- ❌ 错误的格式（会导致显示全部标签） -->
<% if (post.tags && post.tags.length){ %>
  <span class="article-tag">
    <i class="icon icon-tags"></i>
    <%- list_tags({
      tags: post.tags,
      show_count: false,
      style: 'link',
      class: 'article-tag'
    }) %>
  </span>
<% } %>

验证修复结果

1
hexo g

修复后应该能看到正常的生成输出：

1
2
3
4
5
6
INFO  Validating config
INFO  Start processing
INFO  Files loaded in 70 ms
INFO  Generated: posts/vercel-nodejs-upgrade-solution.html
INFO  Generated: index.html
INFO  18 files generated in 97 ms

验证结果

部署完成后，可以通过以下方式验证：

1. 检查部署状态

1
vercel ls

2. 测试网站访问

1
curl -I https://blog.gwbiao.eu.org

正常情况下应该返回 HTTP/2 200 状态码。

3. 查看部署日志

通过 Vercel Dashboard 查看部署日志，确认没有版本错误。

4. 验证 Hexo 生成

确保本地 Hexo 生成没有错误：

1
hexo clean && hexo g

关键要点

  1. 定期关注版本更新：云平台会定期更新支持的运行时版本，需要及时跟进。
  2. 配置文件最佳实践：虽然主要通过 Dashboard 设置，但在项目中维护配置文件是个好习惯。
  3. 主题兼容性检查：Node.js 版本升级后，要检查 Hexo 主题模板的兼容性，特别是辅助函数的参数格式。
  4. 测试验证：升级后一定要测试网站功能是否正常，包括本地生成和线上部署。
  5. 备份配置：在修改配置前，建议备份原有的配置文件。

最终结果

✅ 问题成功解决

  • Node.js 版本从 18.x 升级到 22.x
  • 修复了 Hexo 7.0.0 主题模板兼容性问题
  • 网站正常部署和访问
  • 自定义域名 https://blog.gwbiao.eu.org 工作正常
  • HTTP 状态码：200 OK
  • Hexo 本地生成正常：18 个文件成功生成

总结

Vercel 的 Node.js 版本升级是一个常规的维护操作，但可能会带来一系列兼容性问题。通过 Dashboard 设置是最简单可靠的方法，同时配合项目中的配置文件可以确保项目的可维护性。

本次升级遇到的问题链：

  1. Vercel 平台 Node.js 版本过期 → 需要升级到 22.x
  2. Node.js 22.x 严格检查 → Hexo 主题模板 API 兼容性问题
  3. 主题辅助函数参数格式变化 → 错误修复导致显示全站标签和分类
  4. 重新分析问题 → 保持原有参数格式，修复显示错误

解决思路：

  • 逐个排查错误信息
  • 理解版本升级带来的 API 变化
  • 重要：测试修复后的效果，确保没有引入新问题
  • 全面测试验证修复结果，包括标签和分类的显示

经验教训：

  • 在解决兼容性问题时，不要盲目修改参数格式
  • 修复后一定要验证实际效果，避免引入新问题
  • 保持原有格式往往是最好的解决方案

及时处理这类问题可以保证网站的稳定运行，同时也能积累版本升级的经验。

参考链接：

浪浪山小郎君Developer

Dream big, work hard, stay focused.