经过一番折腾，我的 Hugo 博客正式从本地搬到了 Vercel。这次部署不仅仅是简单的代码上传，还涉及到 Pagefind 全文搜索、私有主题子模块以及基于 Vercel Edge Middleware 的文件夹密码保护。

为了方便以后查阅，也为了给有类似需求的朋友提供参考，特整理此文。

1. 为什么选择 Vercel？

相比于 GitHub Pages 或 Cloudflare Pages，Vercel 的优势在于其强大的 Edge Middleware (边缘中间件)。这让我能够轻松实现“文件夹级别”的访问控制（比如 protected 目录），而不需要维护复杂的后端服务器。

2. 部署前的项目结构调整

为了让 Vercel 能够顺利执行构建任务，我在根目录下补充了一个关键文件：

  • package.json：虽然 Hugo 本身不依赖 Node.js，但我们需要通过它来管理 Pagefind（搜索索引工具）以及 Middleware 运行所需的 @vercel/edge 依赖。有了它，Vercel 才能在构建时自动安装正确的工具链。
1
2
3
4
5
6
7
8
9

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

3. Vercel 导入与配置

在 Vercel 导入 GitHub 仓库时，关键配置如下：

基本信息

  • Application Preset: Hugo
  • Root Directory: ./

构建命令 (Build Command) 🚀

这是一个核心点。因为我们要同时完成 Hugo 构建和 Pagefind 索引生成，所以命令需要连起来写：

1

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

环境变量 (Environment Variables) 🔑

在部署界面的 Environment Variables 栏目添加以下变量，可以极大减少构建失败的概率：

Key Value 说明
HUGO_VERSION 0.157.0 建议与本地版本一致，防止构建语法不兼容
HUGO_BASEURL https://your-domain.com/ 设置你的真实域名，或者使用相对路径 /
AUTH_DURATION 86400 (可选) 加密文章验证后的有效期（秒），默认 1 天

4. 进阶：基于 Middleware 的路径保护

我实现了一个功能：所有放在 content/posts/protected/ 下的文章，在访问时都会被拦截并要求输入密码。

核心逻辑：

  1. middleware.js：在边缘节点拦截请求，校验 Cookie。
  2. password.html：一个简约的毛玻璃视觉风格验证页面。

5. Pagefind 搜索适配

由于 Pagefind 是在静态文件生成后才运行的。我们在构建命令中加入了 npx pagefind，它会自动扫描 public 文件夹并生成索引。 注意：在搜索页面的模板中，要确保引用的是 /pagefind/pagefind-ui.js，路径必须与构建命令中的 --output-path 保持一致。