本文档介绍 jijian 主题的高级功能，包含路径级密码保护、Vercel 部署、GitHub Actions 自动化等进阶内容。

文章内容级本地加密

jijian 主题支持高度安全且跨平台的文章加密功能。与传统的后端验证不同，它在构建阶段对文章正文进行 AES 加密，解密过程完全在访客的浏览器本地完成。

功能特点

  • 强力加密：使用 AES-256-GCM 算法，正文在服务器上以密文形式存储。
  • 跨平台通用：不依赖 Vercel 或 EdgeOne 的特定功能，任何静态托管平台均可运行。
  • 零依赖解密：使用浏览器原生 WebCrypto API，不加载任何外部 JS 库。
  • SEO 友好：加密文章会自动被 Pagefind 搜索索引忽略，保护隐私。
  • 优雅交互：内置极致美观的毛玻璃（Glassmorphism）解锁界面。

配置步骤

1. 为文章设置密码

在文章的 Front Matter（头部信息）中添加 mima 或 password 字段：

1
2
3
4
5

---
title: "我的私密日记"
date: 2024-03-21
mima: "123456" # 也可以使用 password: "xxx"
---

2. 全局参数配置 (hugo.yaml)

在 hugo.yaml 中，您可以统一定义加密页面的行为：

1
2
3
4
5
6
7
8

params:
  # 加密验证有效期 (秒)
  # 默认 3600 (1小时)，0 表示仅限本次访问（浏览器关闭即失效）
  authDuration: 3600
  
  # 自定义加密页面提示语
  # 如果不配置，系统将自动使用多语言默认值（支持 zh-cn/zh-tw/en）
  authTip: "这是一个自定义提示：本站内部资料，请输入密码观看。"

3. 在构建流程中启用加密

静态本地加密 (Static Local Encryption)

jijian 主题内置了一套基于 Node.js 的本地文章加密系统。它在博客构建（Build）阶段执行，将指定的 Markdown 文章内容加密为 AES-256-GCM 格式，并生成美观的、带毛玻璃效果的解密界面。

1. 快速开始

您只需要在文章的 Front Matter 中添加 mima（密码）字段即可：

1
2
3
4
5

---
title: "我的秘密文章"
date: 2024-03-20
mima: "123456" # 或者使用 password: "xxx"
---

2. 构建与加密

要使加密生效，您必须运行包含加密脚本的构建命令。推荐在 package.json 中配置如下脚本：

1
2
3

"scripts": {
  "build": "hugo --gc --minify && node themes/jijian/assets/js/encrypt.js && npx pagefind --site public --output-path public/pagefind"
}

执行 npm run build 后，脚本会自动搜索含有 mima 标签的文章并进行处理。

3. 本地预览加密效果

由于加密指令是写在编译命令中的，直接运行 hugo server 可能无法看到完整的解密 UI（它仅能识别逻辑，但不执行加密脚本）。

推荐的本地测试步骤：

  1. 执行构建：在终端运行 npm run build。
  2. 启动静态服务：使用任何静态服务器查看 public 目录，例如： 
    1

    npx serve public
  3. 访问页面：通过本地服务器地址访问该文章，由于是编译后的结果，您将看到完整的密码输入界面。

主题配置工具 (Config Tools)

为了降低配置负担，主题在根目录提供了一个可视化的配置管理页面：极简（jijian）配置工具-config-tools.html。

核心功能：

  1. 部署一键通：
    • EdgeOne 支持：勾选“部署在腾讯 EdgeOne Pages”后，可指定 Hugo 版本号并直接导出标准的 edgeone.json。
    • 自动依赖生成：自动生成包含加密和搜索指令的 package.json。
  2. 可视化 YAML 管理：以类 App 的界面管理 hugo.yaml 中的菜单、社交图标、页脚信息等，无需直接编辑复杂的 YAML 语法。
  3. 配置快照 (Snapshot)：
    • 如果您担心配置丢失，可以将当前所有设置导出为 .ssjson 快照文件。
    • 下次使用时，只需将该快照文件拖入工具，即可瞬间恢复所有配置并进行再次修改。

路径纠正功能

在配置工具中管理文章路径时，点击输入框旁的 “纠正” 按钮，工具会自动处理以下逻辑：

  • 去除 Windows 式的 \ 反斜杠。
  • 自动识别并去除文章的 .md 后缀。
  • 确保 URL 以 / 开头和结尾。
  • 强制转换为小写，以适配 Hugo 的默认路由行为。

Vercel 部署

Vercel 是部署 Hugo 博客的推荐平台，提供极速的构建流水线和全球分发能力。

为什么选择 Vercel？

  • 极速构建：自动识别 Hugo 环境，构建速度极快
  • 自动 HTTPS：免费 SSL 证书
  • 全球 CDN：通过其边缘网络快速访问
  • 自动部署：推送代码后自动触发生产环境构建
  • 预览环境：每个 PR 都有独立的预览链接

部署前准备

项目结构

your-site/
├── hugo.yaml              # Hugo 配置文件
├── package.json           # Node.js 依赖
├── content/               # 文章内容
├── static/                # 静态资源
└── themes/
    └── jijian/            # 主题文件

package.json

1
2
3
4
5
6
7
8

{
  "name": "your-blog",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "pagefind": "^1.4.0"
  }
}

Vercel 导入配置

1. 导入仓库

在 Vercel 中导入 GitHub 仓库。

2. 配置项目

配置项 值
Framework Preset Hugo
Root Directory ./
Build Command npm run build
Output Directory public

注：推荐在 package.json 中配置好完整的构建脚本，包含 Hugo 生成、加密脚本运行及 Pagefind 索引生成。

3. 环境变量

Key Value 说明
HUGO_VERSION 0.158.0 Hugo 版本，建议与本地一致
HUGO_BASEURL https://your-domain.com/ 站点 URL

构建命令说明

1

hugo --gc --minify && node themes/jijian/assets/js/encrypt.js && npx pagefind --site public --output-path public/pagefind

命令分解：

  • hugo：构建站点
  • --gc：清理未使用的资源
  • --minify：压缩输出
  • && node .../encrypt.js：扫描并加密文章（核心步骤）
  • && npx pagefind：生成搜索索引

自定义域名

1. 添加域名

在 Vercel 项目设置中添加自定义域名。

2. 配置 DNS

根据 Vercel 提示，在域名服务商处配置 DNS 记录。

GitHub Actions 自动化

使用 GitHub Actions 实现自动化部署。注意在工作流中加入 Node.js 环境以运行加密脚本。

基本工作流示例

创建 .github/workflows/gh-pages.yml：

 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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

name: GitHub Pages

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.158.0
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: ${{ env.HUGO_VERSION }}
          extended: true

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: |
          hugo --gc --minify
          node themes/jijian/assets/js/encrypt.js
          npx pagefind --site public --output-path public/pagefind

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Cloudflare Pages 部署

Cloudflare Pages 也支持 Hugo 部署。

配置步骤

1. 导入仓库

在 Cloudflare Pages 中导入 GitHub 仓库。

2. 构建配置

配置项 值
Framework preset Hugo
Build command hugo --gc --minify && node themes/jijian/assets/js/encrypt.js && npx pagefind --site public --output-path public/pagefind
Build output directory public

3. 环境变量

Variable Value
HUGO_VERSION 0.158.0

注意事项

  • 全平台支持：得益于本地静态加密技术，jijian 主题的加密功能在 Cloudflare Pages 上运行良好。
  • 构建环境：确保在 Cloudflare 控制台选择 Hugo 模板。

本地开发优化

使用 Hugo Modules

推荐使用 Hugo Modules 管理主题：

1
2
3

module:
  imports:
    - path: github.com/hcllmsx/hugo-jijian

优点：

  • 无需手动下载主题
  • 方便更新主题

预览草稿

1
2

# 预览草稿文章
hugo server -D

预览未来日期文章

1
2

# 预览未来日期的文章
hugo server -F

性能优化

图片优化

  1. 使用 WebP 格式：Hugo Extended 会自动转换
  2. 配置响应式图片：
1
2
3

params:
  cover:
    responsiveImages: true  #默认已开启，不配置这一项也行。

当你在文章中插入一张 4000 像素的高清大图时，如果不开启此功能，手机用户也必须下载完整的大图，非常耗流量且加载慢。 开启后，Hugo 会在构建时自动为这张图生成 360px、480px、720px 等多个尺寸的缩略图。

注意：这要求图片存放在“文章资源包（Page Bundles）”中（即图片和文章.md文件在同一个文件夹下），或者是博客根目录下的 assets 目录下（没有可以自己新建这个文件夹）的资源。

  1. 图片压缩：使用工具压缩图片后再上传

资源指纹

1
2
3

params:
  assets:
    disableFingerprinting: false    # 默认已启用资源指纹，此处false表示不禁用，就是已启用的意思。

指纹（Fingerprinting）是指在 CSS 和 JS 文件的文件名后面加一串随机的哈希字符。 例如：style.css 变成 style.abcd123.css。

比如你修改了博客的颜色，重新部署：

  • 没有指纹：读者的浏览器可能缓存了旧的 style.css，导致他看到的还是旧颜色，甚至排版错乱（除非他手动刷新）。
  • 有指纹：因为文件内容变了，生成的文件名变成了 style.wxyz456.css。浏览器发现文件名变了，会强制下载最新版。

安全性 (SRI)：开启指纹后，HTML 会包含一个 integrity 校验码。如果你的 CDN 节点被黑客篡改了文件，浏览器会自动拦截，防止恶意代码运行。

构建优化

1
2
3

minify:
  disableXML: true
  minifyOutput: false  #本地预览时选择false 部署的时候已经包含了true

懒加载

主题已内置图片懒加载，无需额外配置。

监控与分析

Google Analytics

在 hugo.yaml 中配置：

1

googleAnalytics: G-XXXXXXXXXX

故障排查

构建失败

  1. 检查 Hugo 版本：确保版本 ≥ 0.146.0
  2. 检查配置语法：YAML 格式是否正确
  3. 检查文章格式：Front Matter 是否正确

搜索不工作

  1. 检查索引生成：确认 Pagefind 索引已生成
  2. 检查路径配置：确保 --output-path 与页面引用一致
  3. 清除缓存：删除 public 和 static/pagefind 后重新构建

样式异常

  1. 清除缓存：删除 resources 目录后重新构建
  2. 检查配置：确认 noClasses: false 已设置
  3. 检查文件路径：CSS 文件是否正确加载

评论不显示

  1. 检查仓库设置：确保 Discussions 已启用
  2. 检查 giscus app：确认已安装并授权
  3. 检查配置参数：确保所有参数正确