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

路径级密码保护

jijian 主题支持在 Vercel 平台上实现"免服务器"的文件夹访问控制。

功能特点

  • 路径保护：保护特定目录下的所有文章
  • 内容锁定：非授权用户无法访问受保护内容
  • 隐私保护：保护区的文章在列表页强制隐藏摘要
  • 自定义有效期：通过环境变量配置授权时长
  • 原地解锁：验证后停留在当前页面

实现原理

通过 Vercel Edge Middleware 拦截请求：

  1. 检查请求路径是否包含 protected
  2. 验证 Cookie 中的授权信息
  3. 未授权则显示密码验证页面
  4. 验证通过后设置 Cookie 并放行

配置步骤

1. 创建受保护的文章

将需要保护的文章放入 content/posts/protected/ 目录：

content/
└── posts/
    ├── protected/
    │   ├── private-article-1.md
    │   └── private-article-2.md
    └── public-article.md

2. 创建 middleware.js

在站点根目录创建 middleware.js：

 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

import { NextResponse } from 'next/server';

const protectedPaths = ['/posts/protected'];
const password = process.env.AUTH_PASSWORD || 'your-password';

export function middleware(request) {
    const { pathname } = request.nextUrl;
    
    // 检查是否是受保护的路径
    if (protectedPaths.some(path => pathname.includes(path))) {
        const cookie = request.cookies.get('auth');
        
        // 验证 Cookie
        if (cookie && cookie.value === 'authorized') {
            return NextResponse.next();
        }
        
        // 返回密码验证页面
        const url = request.nextUrl.clone();
        url.pathname = '/password';
        url.searchParams.set('from', pathname);
        return NextResponse.rewrite(url);
    }
    
    return NextResponse.next();
}

export const config = {
    matcher: '/posts/:path*',
};

3. 创建 package.json

1
2
3
4
5
6
7
8

{
  "name": "your-blog",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "@vercel/edge": "latest"
  }
}

4. 配置环境变量

在 Vercel 项目设置中添加环境变量：

Key Value 说明
AUTH_PASSWORD your-password 访问密码
AUTH_DURATION 86400 授权有效期（秒），默认 1 天

密码验证页面

主题已内置密码验证页面 layouts/page/password.html，提供：

  • 简约的毛玻璃视觉风格
  • 密码输入框和验证按钮
  • 错误提示
  • 验证成功后跳转原页面

文章列表隐藏摘要

受保护的文章会在列表页自动隐藏摘要：

1
2
3
4
5

---
title: "私密文章"
date: 2024-01-01
draft: false
---

注意：路径包含 protected 的文章，主题会自动设置 hideSummary: true。

Vercel 部署

Vercel 是部署 Hugo 博客的推荐平台，提供强大的 Edge Middleware 支持。

为什么选择 Vercel？

  • Edge Middleware：支持边缘计算，实现密码保护等高级功能
  • 自动 HTTPS：免费 SSL 证书
  • 全球 CDN：快速访问
  • 自动部署：推送代码后自动构建部署
  • 预览环境：每个 PR 都有独立的预览链接

部署前准备

项目结构

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

package.json

1
2
3
4
5
6
7
8
9

{
  "name": "your-blog",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "@vercel/edge": "latest",
    "pagefind": "^1.4.0"
  }
}

Vercel 导入配置

1. 导入仓库

在 Vercel 中导入 GitHub 仓库。

2. 配置项目

配置项 值
Framework Preset Hugo
Root Directory ./
Build Command hugo --gc --minify && npx pagefind --site public --output-path public/pagefind
Output Directory public

3. 环境变量

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

构建命令说明

1

hugo --gc --minify && npx pagefind --site public --output-path public/pagefind

命令分解：

  • hugo：构建站点
  • --gc：清理未使用的资源
  • --minify：压缩输出
  • && npx pagefind：生成搜索索引
  • --site public：指定站点目录
  • --output-path public/pagefind：指定索引输出路径

自定义域名

1. 添加域名

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

2. 配置 DNS

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

  • A 记录：指向 76.76.21.21
  • CNAME 记录：指向 cname.vercel-dns.com

3. 更新配置

在 hugo.yaml 中更新 baseURL：

1

baseURL: https://your-domain.com/

GitHub Actions 自动化

使用 GitHub Actions 实现自动化部署。

基本工作流

创建 .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

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.157.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
          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 && npx pagefind --site public --output-path public/pagefind
Build output directory public

3. 环境变量

Variable Value
HUGO_VERSION 0.157.0

注意事项

  • Cloudflare Pages 不支持 Edge Middleware
  • 如需密码保护功能，建议使用 Vercel

本地开发优化

使用 Hugo Modules

推荐使用 Hugo Modules 管理主题：

1
2
3

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

优点：

  • 无需手动下载主题
  • 方便更新主题
  • 版本控制更清晰

更新主题

1
2
3
4
5

# 更新所有模块
hugo mod get -u

# 更新主题到特定版本
hugo mod get github.com/hcllmsx/hugo-jijian@v1.0.0

预览草稿

1
2

# 预览草稿文章
hugo server -D

预览未来日期文章

1
2

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

性能优化

图片优化

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

params:
  cover:
    responsiveImages: true
  1. 图片压缩：使用工具压缩图片后再上传

资源指纹

1
2
3

params:
  assets:
    disableFingerprinting: false    # 启用资源指纹

资源指纹可以：

  • 提高缓存效率
  • 防止缓存冲突

构建优化

1
2
3

minify:
  disableXML: true
  minifyOutput: true

懒加载

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

监控与分析

Google Analytics

在 hugo.yaml 中配置：

1

googleAnalytics: G-XXXXXXXXXX

百度统计

创建 layouts/partials/extend_head.html：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{{ if .Site.Params.analytics.baidu }}
<script>
var _hmt = _hmt || [];
(function() {
  var hm = document.createElement("script");
  hm.src = "https://hm.baidu.com/hm.js?your-baidu-analytics-id";
  var s = document.getElementsByTagName("script")[0];
  s.parentNode.insertBefore(hm, s);
})();
</script>
{{ end }}

在 hugo.yaml 中启用：

1
2
3

params:
  analytics:
    baidu: true

故障排查

构建失败

  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. 检查配置参数：确保所有参数正确