好不容易搭好了博客，提笔第一篇，却寻不出什么话来讲。左右无事，索性将搭建的流程记述一番，也算是一点微不足道的留存。

环境准备

以下环境以 Windows 64 位 为例。别的系统并非不行，只是路数不同，各安其命便是。

关于 Dart Sass

Hugo 的扩展版（extended）内置了 LibSass，用来将 Sass 转译为 CSS。然而天下没有不散的筵席，2020 年，Sass 团队将 LibSass 弃如敝屣，转而推崇 Dart Sass。

Texify3 主题依赖 Dart Sass 编译 SCSS 样式文件。你纵然装了 Hugo Extended，本地却没有 Dart Sass，就好比有了锅却没有米。须得单独装一个，开发与生产方能用上 Sass 的新派功夫，与主题样式保持最佳的契合。

⚠️ 最好与以上版本保持一致。版本不同，容或有参差，轻则样式错乱，重则构建失败，不可不慎。

本地搭建

创建 Hugo 站点

hugo new site Blog
cd Blog

安装主题

❌ 不推荐使用 git submodule 方式引入主题。子模块这东西，部署迁移时还要额外拉取，极易遗漏，徒增烦恼。

✅ 推荐方式：直接将主题克隆到本地 themes/ 目录。整个项目连带着主题都在工作目录里，上传部署一气呵成，无需另寻依赖。

Texify3 主题仓库：git@github.com:michaelneuper/hugo-texify3.git

cd themes
git clone git@github.com:michaelneuper/hugo-texify3.git texify3
cd ..

克隆既毕，主题文件便在 themes/texify3/ 目录中了。然后在 hugo.toml 里添加：

theme = 'texify3'

安装依赖

Texify3 主题靠 PostCSS 来处理 CSS，得通过 npm 把相关依赖装妥：

# Blog 目录下
npm install

⚠️ 注意：npm install 须以管理员身份运行终端，否则权限不足的麻烦，说不得就要找上门来。

启动本地服务

hugo server

启动之后，访问 http://localhost:1313 便可预览博客。开发时无论改了内容还是样式，页面都会自动刷新，省却许多手脚。

停止服务

在终端里按下 Ctrl + C，Hugo 的开发服务器便会歇下了。

部署到静态网站

本地调试已毕，自然要将博客部署到云端，方能与诸君相见。本文选了 腾讯云 EdgeOne Pages 做静态托管，这玩意儿有几样好处：

• 全球加速：依仗腾讯云全球边缘节点，国内首屏加载迅捷，海外访问延迟亦低
• 零运维：不用买服务器，不用配 SSL 证书，也无运维之苦
• 免费额度：公测期间一切功能，尽皆免费开放
• 自动部署：支持 Git 仓库集成，代码一提交便自动构建发布

前置准备

1. 注册腾讯云账号：去 腾讯云 EdgeOne Makers 控制台 完成注册和实名认证
2. Git 仓库：把博客项目推送到 GitHub/GitLab 等远程仓库（供 Git 集成部署之用）
3. 已备案域名（可选）：若要用自定义域名并加速国内，须完成 ICP 备案

新增 EdgeOne 配置文件

EdgeOne Pages 在构建时需要知道你的项目构建方式。虽然 EdgeOne 能够自动识别 Hugo 框架，但为了确保构建环境与本地一致（特别是 Dart Sass 和 npm 依赖），我们需要在项目根目录创建一个 edgeone.json 配置文件。

在项目根目录下新建 edgeone.json，填入以下内容：

{
  "hugoVersion": "0.164.0",
  "buildCommand": "npm install && curl -sfL https://github.com/sass/dart-sass/releases/download/1.102.0/dart-sass-1.102.0-linux-x64.tar.gz | tar -xz && export PATH=\"$PWD/dart-sass:$PATH\" && hugo --minify",
  "outputDirectory": "public"
}

字段说明

构建命令解析

buildCommand 是一行 bash 脚本，按顺序完成四件事：

1. npm install：安装 PostCSS 等 npm 依赖
2. 下载 Dart Sass：从 GitHub 下载 Linux 版 Dart Sass（因 EdgeOne 运行在 Linux 环境）
3. export PATH：将 Dart Sass 加入 PATH，使 Hugo 构建时能找到它
4. hugo --minify：以压缩模式构建 Hugo 站点，减小产物体积

💡 这里的 Dart Sass 下载地址使用的是 Linux 版本（linux-x64），这很重要，不能搞错。

⚠️ 为什么不用 npm install sass ？ 因为 Texify3 主题通过 Hugo Pipes（transpiler: "dartsass"）调用 Dart Sass 的二进制可执行文件来编译 SCSS，而不是通过 Node.js 的 npm 包。所以必须下载 Dart Sass 的二进制版本（.tar.gz / .zip 压缩包），不能通过 npm 安装。如果构建时找不到 Dart Sass 二进制，Hugo 会回退到 LibSass（已废弃），导致主题样式编译失败。

部署方式

EdgeOne Pages 提供四种部署方式，这里介绍第一种，也就是博主所用的方式。

点击导入 Git 仓库，这里需要登录你上传git的仓库，选择你的博客项目如图：

选择要部署的工程后，他会自动识别你所使用的博客框架，如果 Hugo、Hexo 等。这里需要添加必要的信息，具体如图所示：检查完毕后即可点击开始部署。

部署成功后如下图所示：点击预览可以展开默认网址，复制到浏览器中即可查看部署后的博客。

绑定自定义域名

用 EdgeOne 分配的 https://user-blog.edgeone.dev 域名固然可以访问，但若要用自定义域名（比如 escanor.com），还得额外配置：

1. 在 EdgeOne Pages 项目中点击 「域名管理」 → 「添加自定义域名」
2. 输入你的域名（如 www.escanor.org）
3. 按提示到域名服务商处添加 CNAME 解析记录，指向 EdgeOne 提供的加速域名

⚠️ 如果加速区域选的是 中国大陆 或 全球可用区，域名必须已完成 ICP 备案。

配置 HTTPS 证书

域名绑好了，还得配一张 HTTPS 证书，方能加密通信。古人云"不以规矩，不能成方圆"——HTTPS 便是这互联网世界的规矩。EdgeOne 这平台倒也周到，免费证书、强制跳转、HSTS、OCSP 装订，一应俱全。

边缘 HTTPS 证书

EdgeOne 给了两条路：

于个人博客而言，申请免费证书最是省心，零成本零运维。步骤如下：

1. 控制台 → 「域名管理」，寻得已绑定的域名
2. HTTPS 列点击 「配置」
3. 「边缘 HTTPS 证书」卡片点击 「配置」
4. 选「申请免费证书」，验证方式择 「自动验证」，保存
5. 须知域名 CNAME 须正确指向 EdgeOne——CA 机构靠此验明正身，好比官府缉拿要犯，须得画像对得上
6. 静待五至三十分钟，证书签发后自动部署

⚠️ 证书签发之前，HTTPS 暂时不可用。有效期九十天，到期前十五天自动续期，不必挂怀。

强制 HTTPS 访问

开启后，EdgeOne 以 301 重定向（永久重定向），将所有 HTTP 请求自动升级为 HTTPS，全程加密，杜绝偷窥。好比城门之上加了铁闸，闲杂人等不得擅入。

💡 重定向方式有 301（永久）与 302（临时）之别。博主选了 301，搜索引擎会将 HTTP 链接的权重永久转移至 HTTPS，有利于 SEO。若将来可能改回 HTTP，则选 302 为妥。

启用 HSTS

HSTS 者，HTTP Strict Transport Security 也。在响应头中植入 Strict-Transport-Security，勒令浏览器在指定时间内只走 HTTPS 通道。此乃高安全站点之标配，好比在城门铁闸之外，又添了一道护城河。

💡 开 HSTS 务必同时开强制 HTTPS，否则用户首次 HTTP 请求仍可能被中间人乘虚而入。

OCSP 装订

启用后，OCSP 查询由 EdgeOne 边缘节点代办并缓存，TLS 握手时直接响应客户端证书信息，免去客户端向 CA 额外请求之劳。好比将奏折批答之事收归各省总督代办，省去往返京师的时日，效率自是大为提升。

推荐配置组合

博主建议四项尽开，如上图所示。各功能环环相扣，筑就完整的 HTTPS 安全防线：

注意事项

部署之事，说来轻巧，实则坑洼不少。博主初时也跌了几跤，如今记下，免得诸君重蹈覆辙。

Dart Sass 二进制不可用

Texify3 主题依赖 Dart Sass 编译 SCSS，而 EdgeOne 构建环境是 Linux，与本地 Windows 不同。构建命令中须下载 Linux 版 Dart Sass 二进制：

curl -sfL https://github.com/sass/dart-sass/releases/download/1.102.0/dart-sass-1.102.0-linux-x64.tar.gz | tar -xz && export PATH="$PWD/dart-sass:$PATH"

若下载失败（GitHub 在国内访问不稳），Hugo 会回退到已废弃的 LibSass，样式便可能错乱。解法有二：

• 一是换用国内镜像源下载 Dart Sass
• 二是在本地打包好 dart-sass 目录，随项目一同提交至仓库，构建时直接解压即可

npm install 权限问题

本地 npm install 须以管理员身份运行，否则会报 EPERM 权限错误。在 EdgeOne 上倒是无妨——其构建环境默认即是 root 权限，不会有此困扰。

git submodule 部署失效

若当初用 git submodule 引入主题，部署时便会出问题：EdgeOne 构建环境不会自动拉取子模块，导致主题文件缺失，网站一片空白。博主已在"安装主题"一节中提醒过，直接克隆到 themes/ 目录为上策。

图片路径错乱

Typora 默认将图片存至系统临时目录，引用时用的是 Windows 绝对路径，如 C:\Users\...\image.png。本地看无妨，部署后便只剩裂图。须将图片移至项目 static/images/ 目录下，改用 /images/xxx.png 格式引用，方能在生产环境正常显示。

CNAME 未生效致证书签发失败

HTTPS 免费证书依赖 CNAME 验证域名归属，若 CNAME 记录尚未生效便申请证书，CA 机构校验失败，证书便签发不得。须耐心等待 5~30 分钟，DNS 全球生效后再行申请。

构建产物目录不对

Hugo 默认输出至 public/ 目录，EdgeOne 的 edgeone.json 中 outputDirectory 须与之对应。若设错了目录，EdgeOne 找不到构建产物，部署便算失败。