Hexo 部署踩坑记：skip_render 配置无效？原来是缓存惹的祸

四月 10, 2026 3604

问题背景

在将 Viewport 演示工具整合到 Hexo 博客时，我希望保持 demo 页面的原始 HTML 格式，不被 Hexo 的主题布局包裹。

于是我在 _config.yml 中添加了配置：

1
2
skip_render:
  - 'demos/**/*.html'

理论上，source/demos/ 目录下的 HTML 文件应该原样输出到 public/ 目录，不被 Hexo 渲染。

问题现象

执行 hexo generate 后，检查生成的文件：

1
cat public/demos/viewport-demo/index.html

发现文件被包裹上了 Hexo 的主题布局，出现了类似这样的内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<!DOCTYPE html>
<html>
<head>
  <!-- Hexo 主题的 head 内容 -->
  <title>viewport-demo | 博客名称</title>
  <!-- 其他主题注入的内容 -->
</head>
<body>
  <!-- 主题的 header -->
  <header>...</header>
  
  <!-- 我的 demo 内容 -->
  <div class="demo-container">...</div>
  
  <!-- 主题的 footer -->
  <footer>...</footer>
</body>
</html>

配置明明写对了，为什么不生效？

排查过程

1. 检查配置文件语法

1
2
3
4
# 确认 YAML 格式正确
skip_render:
  - 'demos/**/*.html'
  - 'demos/**/*.htm'

2. 检查文件路径

1
2
3
4
5
6
# 确认文件存在
ls -la source/demos/viewport-demo/index.html

# 确认文件没有 front-matter
head -5 source/demos/viewport-demo/index.html
# 应该直接是 <!DOCTYPE html>，没有 ---

3. 检查多种配置写法

1
2
3
4
5
# 尝试不同写法
skip_render:
  - 'demos/**/*'           # 匹配所有文件
  - 'demos/viewport-demo/index.html'  # 精确匹配
  - '**/demos/**/*.html'   # 递归匹配

4. 开启调试模式

1
hexo generate --debug 2>&1 | grep -i "skip\|render\|demos"

输出显示配置已加载，但文件仍被渲染。

真相大白

就在准备放弃时，突然想到可能是缓存问题！

Hexo 会缓存已处理的文件信息，即使修改了配置，旧的缓存仍然存在，导致配置没有真正生效。

验证猜测

1
2
3
4
5
# 查看缓存目录
ls -la db.json
ls -la node_modules/.cache/

# 文件时间戳显示是旧的

解决方案

1
2
3
4
5
6
7
8
9
10
11
# 清理缓存
hexo clean

# 或者使用 npm script
npm run clean

# 重新生成
hexo generate

# 验证结果
cat public/demos/viewport-demo/index.html | head -20

这次终于成功了！文件保持原始格式，没有任何主题包裹。

深入理解：Hexo 的缓存机制

缓存文件位置

1
2
3
4
5
your-hexo-blog/
├── db.json           # 数据库缓存，记录所有文件信息
├── node_modules/
│   └── .cache/       # Hexo 内部缓存
└── public/           # 生成的文件（会被清理）

缓存的作用

  • 加快二次构建速度
  • 避免重复处理相同文件
  • 存储文件哈希值，用于增量更新

什么时候需要清理缓存

场景 是否需要 clean
修改文章内容 ❌ 不需要
修改主题样式 ❌ 不需要
添加新文章 ❌ 不需要
修改 _config.yml ✅ 需要
修改主题配置 ✅ 需要
修改 skip_render ✅ 需要
修改 permalink 规则 ✅ 需要
更新插件 ⚠️ 建议执行
出现奇怪的错误 ✅ 首先尝试

最佳实践

1. 创建便捷的 npm scripts

在 package.json 中添加：

1
2
3
4
5
6
7
8
9
{
  "scripts": {
    "clean": "hexo clean",
    "build": "hexo generate",
    "rebuild": "npm run clean && npm run build",
    "server": "hexo server",
    "dev": "npm run clean && hexo server --debug"
  }
}

2. 开发工作流

1
2
3
4
5
6
7
8
# 修改配置后，使用 rebuild
npm run rebuild

# 本地预览
npm run server

# 部署前总是 clean
npm run clean && hexo deploy

3. Git 忽略缓存文件

在 .gitignore 中添加：

1
2
3
4
5
6
7
8
# Hexo 缓存
db.json
public/
node_modules/.cache/

# 其他临时文件
*.log
.DS_Store

4. 自动化部署脚本

创建 deploy.sh：

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
#!/bin/bash

echo "🚀 开始部署..."

# 清理缓存
echo "📦 清理缓存..."
hexo clean

# 生成静态文件
echo "🔨 生成静态文件..."
hexo generate

# 检查是否生成成功
if [ -d "public" ]; then
    echo "✅ 生成成功"
    
    # 部署
    echo "📤 部署中..."
    hexo deploy
    
    echo "🎉 部署完成！"
else
    echo "❌ 生成失败"
    exit 1
fi

其他常见 skip_render 问题

问题1：路径匹配错误

1
2
3
4
5
6
# ❌ 错误写法
skip_render: demos/**/*.html

# ✅ 正确写法（需要引号和缩进）
skip_render:
  - 'demos/**/*.html'

问题2：文件包含 front-matter

1
2
3
4
5
6
7
8
<!-- ❌ 会被 Hexo 处理 -->
---
title: demo
---
<!DOCTYPE html>

<!-- ✅ 正确：直接 HTML -->
<!DOCTYPE html>

问题3：主题强制包裹

某些主题会强制所有页面使用布局，可以在 front-matter 中禁用：

1
2
3
4
---
layout: false
---
<!DOCTYPE html>

经验总结

  1. 修改配置后记得清理缓存：这是最容易被忽视的问题
  2. 使用 --debug 模式调试：可以看到详细的处理过程
  3. 建立标准化的部署流程：避免遗漏清理步骤
  4. 理解工具的工作原理：Hexo 的缓存机制是为了性能，但有时需要手动干预

相关资源