当前位置： 首页 > news >正文

Hugo 自动化部署实战-部署 Hugo 到 Vercel

news 2025/6/10 7:40:47

欢迎来到 Hugo 自动化部署实战系列教程！在本系列中，我们将逐步探索如何使用 GitHub Actions 将你的 Hugo 静态网站自动化部署到各种流行的托管平台。

本篇作为系列的第一部分，将详细指导你如何设置 GitHub Actions 工作流，以自动化构建你的 Hugo 站点并将其部署到 Vercel。我们将特别关注一种安全且易于管理的凭据管理方式——通过一个集中的 JSON 格式的 GitHub Secret。

后续教程将涵盖部署到 GitHub Pages, Netlify, Cloudflare Pages, 和 Firebase Hosting。

概述：Vercel 部署流程

对于 Vercel 部署，我们将遵循以下主要步骤：

  1. 前置准备: 确保你拥有必要的账户和工具。
  2. 项目设置: 确认你的 Hugo 项目结构。
  3. Vercel 配置: 设置 Vercel 项目并获取部署所需的凭据。
  4. GitHub Secrets 配置: 安全地存储 Vercel 凭据在一个集中的 JSON 对象中。
  5. 创建 GitHub Actions 工作流: 定义自动化构建和部署到 Vercel 的流程。
  6. 提交、测试和验证: 触发部署并检查结果。

1. 前置准备

在开始之前，请确保你已准备好以下各项：

  • 1.1. GitHub 账户和仓库: 你的 Hugo 项目代码应托管在 GitHub 仓库中。
  • 1.2. Vercel 账户: 你需要一个 Vercel 账户 (vercel.com) 来托管你的静态站点。
  • 1.3. Node.js 和 npm/yarn: Vercel CLI 是一个 Node.js 包，它将在 GitHub Actions 环境中被用于部署。本地安装 Node.js (nodejs.org) 也有助于进行一些本地 CLI 操作。
  • 1.4. Hugo 安装 (本地): 在本地安装 Hugo (gohugo.io/installation)，以便能够本地开发和测试你的站点。如果你的主题或内容使用了 SASS/SCSS，请确保安装 Hugo 的 extended 版本。

2. 项目设置 (你的 Hugo 站点)

本教程假设你已经有一个正在运行的 Hugo 项目。

  • 2.1. Hugo 项目初始化: 如果你从头开始，可以使用 hugo new site <site-name>。
  • 2.2. 主题集成: 确保你的 Hugo 主题已正确安装和配置在你的项目中。

在本地运行 hugo server，确认你的 Hugo 站点能够正常构建和预览。

3. Vercel 配置

我们需要在 Vercel 上设置一个项目来接收我们的部署，并获取部署所需的 API 凭据。

3.1. 创建或选择 Vercel 项目

  1. 登录到你的 Vercel 账户。
  2. 点击仪表板上的 “Add New…” -> “Project”。
  3. 选择 “Continue with Git Repository”，然后从列表中选择你的 Hugo 项目所在的 GitHub 仓库。
  4. Vercel 可能会尝试自动检测框架并配置构建设置。你可以暂时接受默认设置，因为我们稍后会在 Vercel 项目设置中禁用其自动构建，以便让 GitHub Actions 完全控制。
  5. 完成项目的导入。

3.2. 获取 Vercel API Token, Project ID, 和 Org ID

这些凭据对于 GitHub Actions 以编程方式与 Vercel API 交互至关重要。

  • VERCEL_TOKEN (Access Token):

    1. 在 Vercel Dashboard，点击右上角你的头像，然后选择 “Settings”。
    2. 在左侧导航栏中，选择 “Tokens”。
    3. 点击 “Create” 按钮。
    4. 为你的 Token 指定一个描述性名称，例如 GitHub Actions - Hugo Vercel Deploy。
    5. 选择 Token 的范围 (Scope)。通常，这会是你的个人账户或你希望部署到的特定 Vercel Team。
    6. （可选但推荐）设置一个过期日期。
    7. 点击 “Create Token”。重要：立即复制生成的 Token 值。它只显示一次。请将其安全保存，稍后会用到。

  • VERCEL_ORG_ID 和 VERCEL_PROJECT_ID (推荐使用 Vercel CLI):
    使用 Vercel CLI 是获取与特定项目关联的 orgId 和 projectId 的最可靠方法。

    1. 安装 Vercel CLI (如果尚未安装):
      npm install -g vercel
    2. 登录 Vercel CLI: 在你的终端运行：
      vercel login
      按照提示在浏览器中完成授权。
    3. 链接本地项目到 Vercel 项目: 在你的本地 Hugo 项目的根目录下，运行：
      cd path/to/your/hugo-site # 替换为你的项目路径
vercel link
      CLI 将引导你：
      • 确认设置当前目录。
      • 选择你的 Vercel scope (这将是你的 orgId 所属的个人账户或团队)。
      • 选择链接到你在 Vercel UI 上为该 Hugo 项目创建的现有项目（或让 CLI 为你创建一个新项目）。
    4. 查看生成的配置: 成功链接后，Vercel CLI 会在你的项目根目录下创建 .vercel/project.json 文件。打开此文件，其内容将类似：
      {"orgId": "team_xxxxxxxxxxxxxxxxx", // 或你的用户 ID"projectId": "prj_yyyyyyyyyyyyyyyyy"
}
      从这个文件中复制 orgId (作为 VERCEL_ORG_ID) 和 projectId (作为 VERCEL_PROJECT_ID) 的值。

3.3. 配置 Vercel 项目以跳过其自身构建

由于我们将使用 GitHub Actions 来构建我们的 Hugo 站点，我们需要告诉 Vercel 不要尝试自行构建。

  1. 在 Vercel Dashboard，导航到你为本文档站点设置的 Vercel Project。
  2. 点击 “Settings” 标签页，然后选择 “Build & Development Settings” 部分。
  3. 找到 “Build Command” 字段，将其清空，或者设置为一个无害的命令，例如 echo "Site is prebuilt and deployed by GitHub Actions"。
  4. “Output Directory” 字段可以保持为 Hugo 的默认 public，或者如果构建命令已清空，此设置影响不大。
  5. “Install Command” 字段也可以清空。
  6. 点击页面底部的 “Save” 按钮。

此设置可确保 Vercel 不会因 Git 推送而触发自动构建，而是等待我们的 GitHub Action 通过 API 进行部署。

4. GitHub Secrets 配置

为了安全地在 GitHub Actions 中使用部署凭据，我们将它们存储在一个名为 DEPLOY_SECRETS_JSON 的 GitHub Secret 中。这个 Secret 将包含一个 JSON 字符串，其中包含所有目标平台（目前是 Vercel）的必要信息。

  1. 导航到你的 Hugo 项目的 GitHub 仓库页面。
  2. 点击仓库顶部的 “Settings” 标签页。
  3. 在左侧菜单中，向下滚动到 “Security” 部分，然后点击 “Secrets and variables” -> “Actions”。
  4. 在 “Repository secrets” 部分，点击 “New repository secret” 按钮。
  5. 创建 Secret:
    • Name: DEPLOY_SECRETS_JSON
    • Secret (Value): 粘贴以下 JSON 结构。请务必将 YOUR_... 占位符替换为你在步骤 3.2 中获取到的实际 Vercel 凭据。 随着系列教程的进行，我们将向此 JSON 对象添加其他平台的凭据。
      {"vercel": {"vercel_token": "YOUR_COPIED_VERCEL_ACCESS_TOKEN","vercel_projectId": "YOUR_VERCEL_PROJECT_ID","vercel_orgId": "YOUR_VERCEL_ORG_ID"}// 未来可以添加 "netlify", "cloudflare_pages", "firebase" 等键
}
      重要提示： 确保粘贴的值是一个有效的 JSON 格式字符串。你可以使用在线 JSON 验证工具来检查其正确性。
  6. 点击 “Add secret”。

5. 创建 GitHub Actions 工作流

现在，我们将编写一个 GitHub Actions 工作流（YAML 文件），它将定义自动化构建和部署到 Vercel 的整个流程。

在你的 Hugo 项目的根目录下，创建 .github/workflows/ 文件夹（如果它尚不存在）。在此文件夹中，创建一个新的 YAML 文件，例如 deploy-hugo-site.yml (一个通用的文件名，因为将来可能会扩展到部署到多个平台)。

将以下内容粘贴到 deploy-hugo-site.yml 文件中：

name: Build Hugo Site & Deploy# 工作流触发器：何时运行此工作流
on:push:branches:- main # 当代码推送到 main 分支时触发 (根据你的主分支名称调整)workflow_dispatch: # 允许从 GitHub UI 手动触发此工作流jobs:# Build Job: 负责构建 Hugo 站点build:name: Build Hugo siteruns-on: ubuntu-latest # 在最新的 Ubuntu 虚拟机上运行permissions:contents: read # 授予读取仓库内容的权限steps:# 步骤 1: 检出仓库代码- name: Checkout repository codeuses: actions/checkout@v4with:submodules: recursive # 如果你的主题是 Git Submodule，则递归拉取fetch-depth: 0       # Hugo 可能需要完整的历史记录来获取 .Lastmod 等信息# 步骤 2: 安装和设置 Hugo CLI- name: Setup Hugo CLIuses: peaceiris/actions-hugo@v2with:hugo-version: 'latest' # 使用最新版 Hugo，或指定特定版本如 '0.123.7'extended: true         # 确保安装 Hugo extended 版本 (如果主题使用 SASS/SCSS)# 步骤 3: 运行 Hugo 构建命令- name: Build Hugo siterun: hugo --minify # --minify 是可选的，用于压缩输出文件# 步骤 4: 上传构建产物 (public 目录)- name: Upload build artifact (public directory)uses: actions/upload-artifact@v4with:name: hugo-build           # Artifact 的名称，将在 deploy job 中使用path: public/             # 要上传的 Hugo 输出目录if-no-files-found: error  # 如果 public 目录为空或不存在，则使步骤失败retention-days: 1         # （可选）保留 artifact 的天数# Deploy to Vercel Job: 负责将构建好的站点部署到 Verceldeploy_vercel:name: Deploy to Vercelif: github.event_name == 'push' || github.event_name == 'workflow_dispatch' # 仅在 push 或手动触发时运行 (可根据需要调整)needs: build # 此 job 依赖于 'build' job 的成功完成runs-on: ubuntu-latestpermissions:contents: read # 通常部署步骤不需要写权限# 设置环境变量，从 DEPLOY_SECRETS_JSON 解析 Vercel 凭据env:VERCEL_TOKEN: ${{ fromJson(secrets.DEPLOY_SECRETS_JSON).vercel.vercel_token }}VERCEL_PROJECT_ID: ${{ fromJson(secrets.DEPLOY_SECRETS_JSON).vercel.vercel_projectId }}VERCEL_ORG_ID: ${{ fromJson(secrets.DEPLOY_SECRETS_JSON).vercel.vercel_orgId }}steps:# 步骤 1: 下载之前构建的 artifact- name: Download build artifactuses: actions/download-artifact@v4with:name: hugo-build           # 必须与 build job 中 upload-artifact 的 name 一致path: ./site-to-deploy   # 将 artifact 下载到当前工作目录下的 ./site-to-deploy 文件夹# 步骤 2: 安装 Node.js (Vercel CLI 需要)- name: Setup Node.js (for Vercel CLI)uses: actions/setup-node@v4with:node-version: '20' # 选择一个与 Vercel CLI 兼容的 Node.js LTS 版本# 步骤 3: 安装 Vercel CLI- name: Install Vercel CLIrun: npm install --global vercel@latest # 安装最新稳定版的 Vercel CLI# 步骤 4: 执行部署命令- name: Deploy to Vercel Productionrun: |echo "Deploying to Vercel Project: $VERCEL_PROJECT_ID under Org/User: $VERCEL_ORG_ID"# Vercel CLI 会自动使用上面通过 'env' 设置的 VERCEL_TOKEN, VERCEL_PROJECT_ID, VERCEL_ORG_ID# 我们直接部署从 artifact 下载的 ./site-to-deploy 目录# '--prod' 标志用于部署到生产环境的 URL# '--yes' 自动确认所有提示，适用于 CI 环境# '--token' 和 '--scope' 是显式传递，尽管环境变量也应该生效，但显式传递更可靠vercel deploy --prod --yes ./site-to-deploy --token "$VERCEL_TOKEN" --scope "$VERCEL_ORG_ID"

6. 提交、测试和验证

6.1. 提交工作流文件到 GitHub

  1. 确保你已将新创建的 .github/workflows/deploy-hugo-site.yml 文件保存在你的本地 Hugo 项目中。
  2. 将此文件添加到 Git 暂存区，提交它，然后推送到你的 GitHub 仓库的 main (或你的主) 分支：
    git add .github/workflows/deploy-hugo-site.yml
git commit -m "ci: Add GitHub Actions workflow to build Hugo and deploy to Vercel"
git push origin main

6.2. 监控 Actions 运行

  1. 一旦你将更改推送到 GitHub，导航到你的仓库页面。
  2. 点击顶部的 “Actions” 标签页。
  3. 你应该会看到一个名为 “Build Hugo Site & Deploy” (或你在 YAML 文件中定义的 name) 的工作流实例正在运行或已排队。
  4. 点击该工作流运行实例，你可以查看 build job 和 deploy_vercel job 的详细日志。
  5. 仔细检查每个步骤的输出，确保没有报告错误。

6.3. 验证部署

  1. 当 deploy_vercel job 成功完成后，其日志输出通常会包含一个指向你已部署站点的生产环境 URL (例如 Production: https://your-project-name.vercel.app)。
  2. 在你的 Web 浏览器中打开这个 URL。
  3. 验证你的 Hugo 站点是否已成功部署并且所有内容均按预期显示。

7. 故障排除和最佳实践

  • Secrets 问题:
    • 如果遇到 Vercel CLI 报告 “No existing credentials found” 或认证失败：
      • 仔细检查 DEPLOY_SECRETS_JSON Secret 的内容。 确保它是一个有效的 JSON 字符串，并且键名 (如 vercel, vercel_token, vercel_projectId, vercel_orgId) 与你在工作流 env 部分中用于 fromJson() 解析的路径完全匹配。
      • 临时调试 (谨慎操作！): 你可以在工作流中临时添加一个步骤来打印环境变量的一部分，以验证 Secret 是否被正确解析和设置 (例如 echo "Token prefix: ${VERCEL_TOKEN:0:5}")。重要：调试完成后，务必立即移除这些打印敏感信息的行，并删除包含这些日志的 Actions 运行记录。
  • Hugo 构建失败:
    • 查看 GitHub Actions 中 Build Hugo site 步骤的日志。Hugo 通常会提供关于错误的明确信息，例如模板错误、内容文件问题或配置 (hugo.toml/config.toml) 错误。
  • Vercel 部署失败:
    • 查看 Deploy to Vercel Production 步骤的日志。Vercel CLI 会报告具体的错误信息。
    • 常见的可能原因包括：无效的 Vercel Token，不正确的 Project ID 或 Org ID，或者 Vercel 服务端的临时问题。
    • 再次确认你已在 Vercel 项目设置中正确清空了 “Build Command”，以防止 Vercel 尝试与 GitHub Actions 同时构建。
  • Artifact 问题:
    • 如果 Download build artifact 步骤失败，请检查 build job 中的 Upload build artifact 步骤是否成功完成，并确认 artifact 的 name (在 upload-artifact 和 download-artifact 中) 是否完全匹配。
    • 确保 path 参数在上传和下载时都指向了正确的目录。
  • 版本固定:
    • 为了提高构建的稳定性和可重复性，考虑在工作流文件中为 Actions (如 actions/checkout@v4, peaceiris/actions-hugo@v2, actions/setup-node@v4) 和工具 (如 Hugo 版本 hugo-version: '0.123.7', Node.js 版本 node-version: '20.x') 指定更精确的版本号，而不是总是依赖 latest 或大版本号。
  • 安全性:
    • 定期审查并按需轮换你的 Vercel Access Token。
    • 遵循最小权限原则：如果你的 GitHub Actions 工作流只需要读取仓库内容，则在 permissions 块中明确指定 contents: read。

恭喜你完成了本系列教程的第一部分！你现在已经掌握了如何使用 GitHub Actions 和集中的 JSON Secret 将 Hugo 站点部署到 Vercel。

在接下来的教程中，我们将探讨如何将 Hugo 站点部署到其他平台，如 GitHub Pages, Netlify, Cloudflare Pages, 和 Firebase Hosting，并可能复用我们已经建立的 build 流程和 DEPLOY_SECRETS_JSON 结构。

http://www.xdnf.cn/news/954757.html

相关文章：

  • macOS 终端智能代理检测
  • Uncaught ReferenceError: process is not defined
  • EU 2023/1669与EU 2023/1670 的区别
  • 前端antd，后端fastapi，实现运行系统指令，并打印运行日志
  • 如何使用CodeRider插件在IDEA中生成代码
  • 6.9-字典序的第K小数字
  • 【记录坑点问题】IDEA运行：maven-resources-production:XX: OOM: Java heap space
  • 【标准解析】商用车CAN网络通信标准（J1939）
  • 【案例篇】为什么设置了 ulimit 但 nofile 限制仍不生效？
  • Cursor 使用分享
  • Java网络编程协议全面解析
  • SQL进阶之旅 Day 22：批处理与游标优化
  • OSPF域内路由
  • 检查项目中的依赖是否有更新——npm outdated
  • Linux基础开发工具——vim工具
  • 2021-03-15 iview一些问题
  • Map相关知识
  • 中小企业碳账本管理指南
  • SpringAI实战：ChatModel智能对话全解
  • 对比一下blender快捷键：p和alt+p
  • 基于Flask前后端分离智慧安防小区系统
  • 定位触发DMA2_Stream1_IRQHandler中断的具体原因简述
  • Spring类型转换融入IOC生命周期
  • 字符串哈希+KMP
  • 五.建造者模式
  • SQLAlchemy的子查询subquery()
  • 日本本社企业直招|Java /cobol/C#/PM/PL/Salesforce/AWS/SAP 等，正社员/個人事業主，高度人才+20 分
  • Spring状态机
  • 苍穹外卖-day02
  • 机器人模仿学习调研（二）