分类: 维护管理

本栏目覆盖内容写完之后的运维事项：在本机预览、构建并部署产物、接入评论与分析、跟随主题版本升级、故障定位。前面五个栏目决定站点的外观与内容，这一栏决定站点能否构建、部署在哪、出问题如何排查。 按任务导航 你要做的事 去哪 在本机看到改动 本地预览 构建出能部署的 public/ 本地预览 部署到 GitHub Pages / Cloudflare / Netlify 发布上线 部署到 example.com/docs/ 这样的子路径 发布上线 让读者在页面底部留言 启用评论 接 Google …

出问题时先做一次干净的生产构建，从第一条错误开始看，后面的多半是级联结果： 终端 rm -rf public resources/_gen hugo --gc --minify --printPathWarnings --panicOnWarning --logLevel info 日志里出现 npm、PostCSS、Autoprefixer 或下载浏览器资源的步骤，说明配置里混进了上游 Docsy 的流程。OINK 消费端的构建只有一条 Hugo 命令。 下面四张表按「症状 → 原因 → 修法 …

升级 OINK 是换一个固定的模块版本，再确认站点仍能零告警构建。内容多数不用改；需要改的场景（0.4 的 shortcode 换成 v5 的 Markdown 原生形态）有一个可以干跑的迁移工具，不必手改几百个文件。 升级会改变渲染结果。先建一个升级分支再动手，回退的代价就是丢弃一个分支。 先看发布注记 每个版本的变更、破坏性改动与升级要点都写在发布注记里，升级前先读一遍目标版本那篇： 本站的 项目博客 里的 release 系列 GitHub 上的 Releases 页面 注记说明这次要不要 …

主题默认不加载任何分析、表单或广告脚本，不配置就没有对外请求。接入需要显式配置，并把这条外部数据边界写进站点的隐私说明。SEO 一侧相反：canonical、hreflang、robots meta、Open Graph 与 Twitter 卡片由主题逐页生成，需要你做的是把 baseURL 与每页的 description 写对。 接 Google Analytics 用 Hugo 内置的服务配置，填 GA4 的 measurement ID： hugo.yml services: …

OINK 的评论走 giscus：每个页面对应一条 GitHub Discussion，读者用 GitHub 账号登录后发言，维护者在 GitHub Discussions 里审核与管理。主题不提供自建评论后端，也不内置 giscus 以外的服务商。 前提是一个公开的 GitHub 仓库，访客读不到私有仓库的 Discussions。 这是主题里少数对外发请求的功能 启用评论的页面会从 https://giscus.app 加载脚本和 iframe，网络隔离环境里用不了。它默认关闭，只在显式打开 …

OINK 站点的产物是一个纯静态目录，任何能托管静态文件的地方都能部署，不需要 Node 运行时、服务端渲染或构建插件。托管商一侧只有三件事：用正确的 Hugo 版本执行一条命令、发布 public/、让 baseURL 与最终访问地址一致。 前提是本机已经能完成零告警的生产构建。 确定 baseURL baseURL 是最常见的故障源，失败方式也隐蔽：页面能打开，但搜索索引 404、页面操作链接指向错误位置、部分资源加载失败。 部署到域名根目录： hugo.yml baseURL: …

两条命令覆盖日常工作：hugo server 在本机预览改动，hugo 产出可以部署到任何静态托管的 public/。前提是本机安装了 Hugo Extended（不低于 0.160.1）；用 Hugo Module 引入主题时还需要 Go。构建不依赖 Node.js、npm 与 PostCSS，它们只服务于本仓库自身的回归检查。 预览服务器 在站点根目录（hugo.yml 所在的目录）执行： 终端 hugo server 打开 http://localhost:1313/。保存文件后 Hugo …