[{"content":"主站 - gweb.work.gd 或 lgcr837.github.io\nCDN - fast.gweb.work.gd 或 lgcr837-github-io.pages.dev\n这个博客是在 2026 年 4 月 19 日 完成的。\n这个博客由 Hugo 驱动，使用 Stack 主题，部署在 GitHub Pages 上，因为 Hugo 产生的文件是完全静态的。我想分享一下我的过程和遇到的坑，但不要完全照着我的来。\nHugo 可以选择很多主题，最初，我选择 PaperMod 主题，但发现过于简陋，于是选择了 Stack 主题。这是一个卡片式的主题，看起来现代且美观。\n为了在 Github Pages 上完成部署，我把老仓库改了个名字，然后重新新建仓库 lgcr837.github.io。\n我最初使用了 Github Codespace 来减轻前期调试的负担。\n初始化 Hugo 站点 打开这个仓库，创建一个 Github Codespace，打开在线 VSCode 的终端。\n错误示范 温馨提示：这是错误示范，是常见误区，不建议执行这一小章节的任何代码内容。\n我来演示一下我最初的错误做法\n我先安装了 Hugo\n1 2 3 $ wget https://github.com/gohugoio/hugo/releases/download/v0.160.1/hugo_0.160.1_linux-amd64.deb $ sudo dpkg -i hugo_0.160.1_linux-amd64.deb $ rm hugo_0.160.1_linux-amd64.deb 先确认一下 Hugo 版本\n1 2 $ hugo version hugo v0.160.1-7747abbb316b03c8f353fd3be62d5011fa883ee6 linux/amd64 BuildDate=2026-02-25T16:38:33Z VendorInfo=gohugoio 确认了 Hugo 已经安装之后，准备初始化 Hugo 站点\n1 2 3 $ hugo new site . --force Congratulations! Your new Hugo site is created in /workspaces/lgcr837.github.io. ... 继续\n1 2 3 4 5 $ git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git themes/hugo-theme-stack $ cp -r themes/hugo-theme-stack/demo/* . $ cp -r themes/hugo-theme-stack/demo/.gitignore . 2\u0026gt;/dev/null $ hugo --theme hugo-theme-stack --ignoreVendorPaths=\u0026#34;**\u0026#34; ERROR error building site: render: ... TOCSS: failed to transform ... this feature is not available in your current Hugo version, see https://goo.gl/YMrWcn for more information 看样子已经初始化完成了，吗？ 看提示信息没法正常构建，因为 Stack 主题使用了 SCSS ，但 Hugo 普通版不带有编译 SCSS 功能，会构建错误，需要安装 Extended 版本。\n正确示范 安装正确的 Hugo 版本\n1 2 3 4 5 wget https://github.com/gohugoio/hugo/releases/download/v0.160.1/hugo_extended_0.160.1_linux-amd64.tar.gz tar -xzf hugo_extended_0.160.1_linux-amd64.tar.gz sudo mv hugo /usr/local/bin/hugo sudo chmod +x /usr/local/bin/hugo rm hugo_extended_0.160.1_linux-amd64.tar.gz 这样就安装完成了 Extended 版本，看一下版本号有 +extended 就对了\n1 2 $ hugo version hugo v0.160.1-d6bc8165e62b29d7d70ede01ed01d0f88de327e6+extended linux/amd64 BuildDate=2026-04-08T14:02:42Z VendorInfo=gohugoio 添加 Stack 主题，添加为 Git 子模块。\n1 git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git themes/hugo-theme-stack 初始化 Hugo 站点\n1 hugo new site . --force 之后复制主题的示例配置， Stack 主题的示例文件在 demo 文件夹下，配置在 config/_default/ 下，Stack 使用多文件配置。\n1 2 cp -r themes/hugo-theme-stack/demo/* . cp -r themes/hugo-theme-stack/demo/.gitignore . 2\u0026gt;/dev/null 先尝试启动一下测试服务器来测试效果。(可选)\n1 2 3 $ hugo server -D --theme hugo-theme-stack --bind 0.0.0.0 --port 1313 --disableLiveReload Web Server is available at http://localhost:1313/ (bind address 0.0.0.0) ... 这样测试服务器就在 Codespace 的 1313 端口开放了。\n备注：在 VSCode 终端的端口选项卡里可以找到转发的端口\n现在服务器大致能正常运行了，但如果每次编辑都打开 Codespace 重新部署不太现实，我们可以使用 Github Actions 进行自动部署。\n新建一个 Action -\u0026gt; .github/workflows/hugo.yaml\n1 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 name: Deploy Hugo site to Pages on: push: branches: [\u0026#34;main\u0026#34;] workflow_dispatch: permissions: contents: read pages: write id-token: write concurrency: group: \u0026#34;pages\u0026#34; cancel-in-progress: false jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 with: submodules: recursive - name: Setup Hugo uses: peaceiris/actions-hugo@v3 with: hugo-version: \u0026#39;0.160.1\u0026#39; extended: true - name: Build run: hugo --minify --theme hugo-theme-stack - 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 这样就会在每一次提交的时候自动部署。 现在来到仓库 Setting -\u0026gt; Pages -\u0026gt; Source，选择 Github Actions，这样就会自动部署到 Github Pages 上了，然后稍等片刻就能在 Github Pages 上的网址看到效果，lgcr837.github.io。\n注意，如果代码是在 Codespace 编辑的记得提交。\n1 2 3 git add . git commit -m \u0026#34;Gooooooooooooooooooooooooooooooooood Job\u0026#34; git push 现在整个博客就完成了部署。\n添加新文章 要添加新文章，就直接进入这个仓库的content/post/文件夹，然后新建xxxxx.md文件。\nHugo 的文章最前面要添加一个下面这个不然没法识别\n1 2 3 4 5 6 7 8 9 10 11 12 13 --- title: \u0026#34;这是标题\u0026#34; date: 2026-04-26 draft: false categories: [\u0026#34;这是一个分类\u0026#34;] tag: [Hugo, 教程] description: \u0026#34;文章描述\u0026#34; author: \u0026#34;作者名\u0026#34; authorLink: \u0026#34;https://example.com\u0026#34; image: \u0026#34;/img/xxxxx.jpg\u0026#34; slug: \u0026#34;custom-url\u0026#34; weight: 1 --- 其中这几个为必须因素\n参数 说明 title 文章标题 date 写作时间 draft 是否是草稿（草稿不会显示在文章列表中） 其中这几个为可选因素\n参数 类型 说明 tag 字符串/数组 文章标签，例如 tag: [Hugo, 教程] categories 字符串/数组 文章分类 description 字符串 文章描述或摘要，显示在文章列表页 author 字符串 作者名称 authorLink 字符串 作者链接 image 字符串 封面图路径，如 /img/xxxxx.jpg slug 字符串 自定义URL路径 weight 整数 置顶权重，越小越前 comments 布尔值 是否开启评论 toc 布尔值 是否显示文章目录 math 布尔值 是否启用 LaTeX 公式 mermaid 布尔值 是否启用 Mermaid 图表 externalLink 字符串 外部链接，设置后点击文章卡片跳转外部网址 cover.hidden 布尔值 是否在文章内页隐藏封面图 更多配置 更改默认语言 当你第一次进入网站，会发现界面的默认语言还是英语，只能在左下角的设置手动修改。其实可以通过配置文件的方式修改默认语言。 我来到 config/_default/hugo.toml 修改并添加添加这样一行把中文设置为默认语言，并加入中日韩文字适配(不然还是容易出问题)。\n1 2 defaultContentLanguage = \u0026#34;zh\u0026#34; hasCJKLanguage = true 然后似乎就成功了。\n修改基本信息 来到 config/_default/hugo.toml ，这里能够修改网站的基本信息。\n1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 baseURL = \u0026#34;这里请填写你的网站的链接(如https://lgcr837.github.io)\u0026#34; languageCode = \u0026#34;zh-cn\u0026#34; title = \u0026#34;网站名称\u0026#34; defaultContentLanguage = \u0026#34;zh\u0026#34; hasCJKLanguage = true [pagination] pagerSize = 5 [permalinks] post = \u0026#34;/p/:slug/\u0026#34; page = \u0026#34;/:slug/\u0026#34; [services.disqus] shortname = \u0026#34;hugo-theme-stack\u0026#34; 我尝试修改头像，我发现默认的头像是 assets/img/avatar.png ，但我的头像文件是 avatar.webp 文件没法直接替换，所以把自己的头像文件也放进 assets/img/ 文件夹中，然后来到 config/_default/params.toml 替换头像路径。\n1 2 3 4 5 6 ... favicon = \u0026#34;img/avatar.webp\u0026#34; ... [sidebar] avatar = \u0026#34;img/avatar.webp\u0026#34; ... 添加评论系统 我决定给博客添加评论系统，考虑到 Giscus 无需服务器即可部署，且 Stack 主题原生支持。\n部分版本的 Stack 主题会默认启用 Disqus 评论，但这个国内没法用，我们需要将它去除，否则会和 Giscus 产生冲突。 在 config/_default/params.toml 当中找到 [comments.disqus]一整段删了，然后把[comments]修改如下。\n1 2 3 [comments] enabled = true provider = \u0026#34;giscus\u0026#34; 然后开始添加 Giscus，进入仓库设置，Settings -\u0026gt; General -\u0026gt; Features -\u0026gt; 勾选 Discussions，这样确保讨论功能开启，因为 Giscus 的原理就是基于这个。\n我们现在给仓库安装 Giscus 应用，打开 GitHub Apps - Giscus 安装 Giscus，注意不要选择全部仓库而是选择你的博客仓库。\n然后来到 giscus.app/zh-CN，填写相关内容。\n仓库 填写 用户名/仓库，如 LGCR837/lgcr837.github.io 页面 discussion 映射关系 保持默认即可，Discussion 的标题包含页面的 pathname 分类 建议选择General因为最适合作为评论，天生为评论所生。强烈不建议使用Announcements，因为这样只有你自己能发表评论，除非你本来的意愿就是这样。 特性 按需勾选，但也分享一下我的做法 [ √ ] 启用主帖子上的反应（reaction） [ ] 输出 discussion 的元数据 [ √ ] 将评论框放在评论上方 [ √ ] 懒加载评论 主题 按需选择即可 然后下面会自动生成一个代码，把它复制到文本编辑器中我们需要稍作修改。\n以这一段为例\n1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 \u0026lt;script src=\u0026#34;https://giscus.app/client.js\u0026#34; data-repo=\u0026#34;LGCR837/lgcr837.github.io\u0026#34; data-repo-id=\u0026#34;R_kgDOSGj-Ag\u0026#34; data-category=\u0026#34;General\u0026#34; data-category-id=\u0026#34;DIC_kwDOSGj-As4C7tiD\u0026#34; data-mapping=\u0026#34;pathname\u0026#34; data-strict=\u0026#34;0\u0026#34; data-reactions-enabled=\u0026#34;1\u0026#34; data-emit-metadata=\u0026#34;0\u0026#34; data-input-position=\u0026#34;bottom\u0026#34; data-theme=\u0026#34;preferred_color_scheme\u0026#34; data-lang=\u0026#34;zh-CN\u0026#34; crossorigin=\u0026#34;anonymous\u0026#34; async\u0026gt; \u0026lt;/script\u0026gt; 把他转写成 Hugo Stack 的 toml 格式\n1 2 3 4 5 6 7 8 9 10 11 12 13 14 [comments.giscus] repo = \u0026#34;LGCR837/lgcr837.github.io\u0026#34; repoId = \u0026#34;R_kgDOSGj-Ag\u0026#34; category = \u0026#34;General\u0026#34; categoryId = \u0026#34;DIC_kwDOSGj-As4C7tiD\u0026#34; mapping = \u0026#34;pathname\u0026#34; strict = false reactionsEnabled = true emitMetadata = false inputPosition = \u0026#34;bottom\u0026#34; theme = \u0026#34;preferred_color_scheme\u0026#34; lang = \u0026#34;zh-CN\u0026#34; crossorigin = \u0026#34;anonymous\u0026#34; async = true 转换的过程可以大致遵循下面这个表格 (表格没有列出全部的，一些比较罕见的设置自己搜索)\n原本名称 TOML 名称 格式变化 repo repo repo-id repoId category category category-id categoryId mapping mapping term term strict strict \u0026quot;0\u0026quot; → false，\u0026quot;1\u0026quot; → true reactions-enabled reactionsEnabled \u0026quot;1\u0026quot; → true，\u0026quot;0\u0026quot; → false emit-metadata emitMetadata \u0026quot;0\u0026quot; → false，\u0026quot;1\u0026quot; → true input-position inputPosition theme theme lang lang loading loading data-loading loading 如 \u0026ldquo;lazy\u0026rdquo; 等 crossorigin crossorigin 然后我们把这一段 toml 添加在 config/_default/params.toml 当中。\n温馨提示：请务必填写你的信息，不要照抄本文示例\n使用 Cloudflare Pages 进行加速 进入 Cloudflare 的控制台 ，进入 Workers \u0026amp; Pages 页面，新建一个 Pages，选择 连接 Github 仓库，然后按照指示给仓库安装应用，注意请选定一个仓库而不是默认的全部仓库。 然后按照下面这样的方式进行配置。\n框架预设 - 在下拉框选择 Hugo 构建命令 - hugo --minify --theme hugo-theme-stack 构建输出目录 - /public 随后添加一个环境变量，用来防止自动使用旧版 Hugo 造成不兼容。 HUGO_VERSION - 0.160.1 然后点击 保存并部署 ，稍等片刻即可使用 lgcr837-github-io.pages.dev 加速访问。之后每一次 Github 仓库的提交都会自动进行部署。 ","date":"2026-04-28T00:00:00Z","permalink":"/p/hugo-stack-%E5%8D%9A%E5%AE%A2%E6%90%AD%E5%BB%BA%E8%AE%B0%E5%BD%95/","title":"Hugo Stack 博客搭建记录"},{"content":"网站成功在 CloudFlare Pages 上完成了 CDN 部署，现在可以访问以下域名：推荐使用 fast.gweb.work.gd 访问本站以获得最快的访问速度。\n主站 - gweb.work.gd CDN - lgcr837-github-io.pages.dev CDN - fast.gweb.work.gd ","date":"2026-04-26T00:00:00Z","permalink":"/p/cdn-%E6%90%AD%E5%BB%BA%E5%AE%8C%E6%AF%95/","title":"CDN 搭建完毕"}]