部署问题记录 - 2026-05-20

问题概述

本次主要遇到以下问题：

1. 子模块获取失败
2. “No layout” 警告导致页面空白
3. pnpm 与 npm 冲突
4. Vercel 部署配置问题

问题 1: 子模块获取失败

现象

1
2

Warning: Failed to fetch one or more git submodules
fatal: remote error: upload-pack: not our ref 38f8a7a...

原因

• 子模块的提交在上游远程仓库中不存在
• 本地修改的子模块未推送到远程

解决方案

1. 将子模块 URL 改为用户的 fork 仓库
2. 推送子模块更改到 fork 仓库
3. 更新主项目的子模块引用

操作步骤

1
2
3
4
5
6
7

# 修改子模块 URL
git config -f .gitmodules submodule.themes/kratos-rebirth.url https://github.com/drfengyu/Kratos-Rebirth.git

# 推送子模块到 fork
cd themes/kratos-rebirth
git remote add fork https://github.com/drfengyu/Kratos-Rebirth.git
git push fork v2 -f

问题 2: “No layout” 警告

现象

1
2
3
4

WARN No layout: archives.html
WARN No layout: index.html
WARN No layout: 2026/05/20/hello-world/index.html
...

原因

1. hexo-renderer-ejs 未正确安装或版本不兼容
2. hexo-generator-index v4 与 Hexo 8.x 不兼容

解决方案

1
2
3
4
5

# 重新安装 hexo-renderer-ejs
npm install hexo-renderer-ejs --save

# 降级 hexo-generator-index 到 v3
npm install hexo-generator-index@3 --save

问题 3: pnpm 与 npm 冲突

现象

1
2

ERROR Plugin load failed: hexo-generator-category
Error: EISDIR: illegal operation on a directory, read

原因

Vercel 使用 pnpm，但 pnpm 的模块结构与 npm 不同，导致路径解析问题。

解决方案

1. 删除 pnpm-lock.yaml
2. 使用 npm 重新安装依赖
3. 更新 Vercel 配置使用 npm

操作步骤

1
2
3
4
5
6

# 删除 pnpm 相关文件
rm -f pnpm-lock.yaml
rm -rf node_modules

# 使用 npm 安装
npm install

问题 4: Vercel 部署配置

现象

Vercel 构建时子模块未正确初始化

解决方案

创建 vercel.json 配置文件：

1
2
3
4
5

{
  "buildCommand": "git submodule update --init --recursive && npm install && npm run build",
  "outputDirectory": "public",
  "framework": null
}

问题 5: .github 目录未删除

现象

子模块中包含不必要的 .github 目录

原因

之前删除 .github 的提交在子模块中，但未推送到远程仓库

解决方案

1
2
3
4
5

cd themes/kratos-rebirth
rm -rf .github
git add -A
git commit -m "chore: 删除 .github 目录"
git push fork v2 -f

最终配置

package.json

1
2
3
4
5
6
7
8
9
10
11

{
  "engines": {
    "node": ">=18.0.0"
  },
  "scripts": {
    "build": "hexo generate",
    "clean": "hexo clean",
    "deploy": "hexo deploy",
    "server": "hexo server"
  }
}

vercel.json

1
2
3
4
5

{
  "buildCommand": "git submodule update --init --recursive && npm install && npm run build",
  "outputDirectory": "public",
  "framework": null
}

.gitmodules

1
2
3
4

[submodule "themes/kratos-rebirth"]
	path = themes/kratos-rebirth
	url = https://github.com/drfengyu/Kratos-Rebirth.git
	branch = v2

经验教训

1. 子模块管理：本地修改的子模块必须推送到远程仓库，否则其他环境无法获取
2. 依赖管理：pnpm 和 npm 的模块结构不同，可能导致路径问题
3. 版本兼容性：Hexo 插件版本需要与 Hexo 主版本兼容
4. Vercel 配置：需要明确指定构建命令和子模块初始化

相关提交

• cd94370 - docs: 添加问题排查记录
• 5e195d9 - chore: 更新子模块（删除 .github）
• 6e8d170 - chore: 修改子模块 URL 为用户仓库
• c391262 - chore: 在 Vercel 构建中添加子模块初始化
• 2ef8cb6 - chore: 使用 npm 替代 pnpm