[{"content":"","date":"September 9, 2026","externalUrl":null,"permalink":"/en/categories/","section":"Categories","summary":"","title":"Categories","type":"categories"},{"content":"这是用 Hugo + Pages CMS + GitHub Pages 发布的第一篇文章。\n如果本地预览和线上都能看到这段文字，说明搭建成功。\n","date":"September 9, 2026","externalUrl":null,"permalink":"/en/posts/hello-world/","section":"Posts","summary":"","title":"Hello，World","type":"posts"},{"content":"","date":"September 9, 2026","externalUrl":null,"permalink":"/en/","section":"QiYue's Blog","summary":"","title":"QiYue's Blog","type":"page"},{"content":"","date":"September 9, 2026","externalUrl":null,"permalink":"/en/tags/","section":"Tags","summary":"","title":"Tags","type":"tags"},{"content":"","date":"September 9, 2026","externalUrl":null,"permalink":"/en/categories/%E5%8D%9A%E5%AE%A2/","section":"Categories","summary":"","title":"博客","type":"categories"},{"content":"","date":"September 9, 2026","externalUrl":null,"permalink":"/en/tags/%E9%9A%8F%E7%AC%94/","section":"Tags","summary":"","title":"随笔","type":"tags"},{"content":" 1. 前置准备 # 需要：\nGitHub 账号 本机 Git for Windows 本机 Hugo Extended（下文离线安装） 建议先装 Git，再装 Hugo。两者都用安装包 / zip，不走包管理器。\n1.1 离线安装 Git # 打开 https://git-scm.com/download/win 下载 64-bit Git for Windows Setup（.exe） 双击安装，选项保持默认 关键一项选 Git from the command line and also from 3rd-party software 装完后新开 PowerShell，执行： PowerShell\ngit --version 应输出类似 git version 2.x.x.windows.x。\n第一次使用 Git，再执行一次（只做一次）：\nPowerShell\ngit config --global user.name \u0026#34;你的名字\u0026#34; git config --global user.email \u0026#34;你的邮箱@example.com\u0026#34; 1.2 离线安装 Hugo Extended # 不要用：\nPowerShell\nwinget install Hugo.Hugo.Extended 按下面做。\n下载正确的压缩包 # 打开官方发布页：\nhttps://github.com/gohugoio/hugo/releases/latest\n当前版本以 v0.165.0 为例。滚到 Assets，只下载这一份：\n电脑类型 文件名 普通 64 位 Windows（绝大多数） hugo_extended_0.165.0_windows-amd64.zip ARM 电脑（Surface Pro X 等） hugo_extended_0.165.0_windows-arm64.zip 64 位直链：\nhttps://github.com/gohugoio/hugo/releases/download/v0.165.0/hugo_extended_0.165.0_windows-amd64.zip\n不要下载：\nhugo_0.165.0_windows-amd64.zip（没有 Extended，主题容易编不过） Source code (zip) / Source code (tar.gz)（源码，不是安装包） .deb / .tar.gz（Linux 包） 安装包大约 20MB。可以先下载再拷到离线电脑。\n解压到固定目录 # 建议放到不含空格、不会被清理的目录，不要留在「下载」里。\n在 C:\\ 下新建 C:\\Hugo\\bin 右键 zip → 全部提取 把解压出来的 hugo.exe 复制到 C:\\Hugo\\bin\\ 解压后通常有：\ntext\nhugo.exe ← 只要这一个 LICENSE README.md 最后应是：\ntext\nC:\\Hugo\\bin\\hugo.exe 把目录加入 PATH（图形界面） # 按 Win 键，搜索：编辑系统环境变量 点 环境变量 上面「用户变量」里选中 Path → 编辑 新建，填： text\nC:\\Hugo\\bin 一路确定保存 关掉所有已经打开的 PowerShell / CMD / Windows Terminal，再新开一个 验证 # 新开 PowerShell：\nPowerShell\nhugo version 成功时应类似：\ntext\nhugo v0.165.0+extended windows/amd64 ... 必须看到 +extended。如果提示「无法将 hugo 项识别为 cmdlet」：\nPATH 没加对，或旧终端没关 hugo.exe 不在 C:\\Hugo\\bin 下载了错的 zip 可再确认：\nPowerShell\nGet-Command hugo | Format-List Test-Path C:\\Hugo\\bin\\hugo.exe 以后升级 Hugo：再下一个新版本 zip，用新的 hugo.exe 覆盖 C:\\Hugo\\bin\\hugo.exe，不用改 PATH。本地版本尽量和后面 workflow 里的 HUGO_VERSION 一致。\n2. 创建 GitHub 仓库 # 打开 https://github.com/new 仓库名必须是：你的用户名.github.io\n例如用户名是 alice，仓库就叫 alice.github.io 选 Public 不要勾选 Add a README 点 Create repository 记下仓库地址，例如：\ntext\nhttps://github.com/alice/alice.github.io.git 用户站最终网址：\ntext\nhttps://alice.github.io 如果用项目站（仓库名任意），网址会变成 https://用户名.github.io/仓库名/，baseURL 也要带上仓库名。个人博客建议用用户站。\n3. 本地初始化 Hugo 站点 # 把下面的 alice 全部换成你的 GitHub 用户名。在 PowerShell 里执行：\nPowerShell\ncd $HOME git clone https://github.com/alice/alice.github.io.git cd alice.github.io # 目录已有 .git，必须加 --force hugo new site . --force --format toml 加上主题。这里用 PaperMod，以 git submodule 方式添加，这样 GitHub Actions 才能拉到主题：\nPowerShell\ngit submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod git submodule update --init --recursive 建图片目录、文章目录：\nPowerShell\nNew-Item -ItemType Directory -Force -Path static\\images, content\\posts 在仓库根目录新建 .gitignore：\ngitignore\n/public/ /resources/_gen/ .hugo_build.lock 不要把 public/ 提交进仓库。Hugo 每次构建都会重新生成它。\n4. 写 Hugo 配置 # 覆盖仓库根目录的 hugo.toml（把 alice、标题、作者改成你的）：\ntoml\nbaseURL = \u0026#39;https://alice.github.io/\u0026#39; languageCode = \u0026#39;zh-cn\u0026#39; defaultContentLanguage = \u0026#39;zh-cn\u0026#39; title = \u0026#39;我的博客\u0026#39; theme = \u0026#39;PaperMod\u0026#39; hasCJKLanguage = true enableRobotsTXT = true enableGitInfo = true pagination.pagerSize = 8 [caches.images] dir = \u0026#39;:cacheDir/images\u0026#39; [params] env = \u0026#39;production\u0026#39; description = \u0026#39;用 Hugo + Pages CMS 搭建的个人博客\u0026#39; author = \u0026#39;Alice\u0026#39; defaultTheme = \u0026#39;auto\u0026#39; ShowReadingTime = true ShowShareButtons = false ShowPostNavLinks = true ShowBreadCrumbs = true ShowCodeCopyButtons = true ShowRssButtonInSectionTermList = true ShowFullTextinRSS = false disableThemeToggle = false DateFormat = \u0026#39;2006-01-02\u0026#39; [params.homeInfoParams] Title = \u0026#39;你好，这里是 Alice\u0026#39; Content = \u0026#39;技术随笔 / 笔记 / 个人博客\u0026#39; [[params.socialIcons]] name = \u0026#39;github\u0026#39; url = \u0026#39;https://github.com/alice\u0026#39; [menu] [[menu.main]] identifier = \u0026#39;posts\u0026#39; name = \u0026#39;文章\u0026#39; url = \u0026#39;/posts/\u0026#39; weight = 10 [[menu.main]] identifier = \u0026#39;tags\u0026#39; name = \u0026#39;标签\u0026#39; url = \u0026#39;/tags/\u0026#39; weight = 20 [[menu.main]] identifier = \u0026#39;archives\u0026#39; name = \u0026#39;归档\u0026#39; url = \u0026#39;/archives/\u0026#39; weight = 30 [[menu.main]] identifier = \u0026#39;search\u0026#39; name = \u0026#39;搜索\u0026#39; url = \u0026#39;/search/\u0026#39; weight = 40 [outputs] home = [\u0026#39;HTML\u0026#39;, \u0026#39;RSS\u0026#39;, \u0026#39;JSON\u0026#39;] PaperMod 的搜索页和归档页需要两个特殊文件。\ncontent/search.md：\nMarkdown\n--- title: \u0026#34;搜索\u0026#34; layout: \u0026#34;search\u0026#34; summary: \u0026#34;search\u0026#34; placeholder: \u0026#34;输入关键词\u0026#34; --- content/archives.md：\nMarkdown\n--- title: \u0026#34;归档\u0026#34; layout: \u0026#34;archives\u0026#34; summary: \u0026#34;archives\u0026#34; --- 再写一篇测试文章 content/posts/hello-world.md：\nMarkdown\n--- title: \u0026#34;你好，世界\u0026#34; date: 2026-09-09T12:00:00+08:00 draft: false description: \u0026#34;这是第一篇文章，用来验证站点能编译、能发布。\u0026#34; tags: - 随笔 categories: - 博客 --- 这是用 **Hugo + Pages CMS + GitHub Pages** 发布的第一篇文章。 如果本地预览和线上都能看到这段文字，说明搭建成功。 本地先跑起来确认没问题：\nPowerShell\nhugo server -D 终端里会出现类似 http://localhost:1313/。浏览器打开，应能看到首页和《你好，世界》。能打开后再 Ctrl+C 停掉。\n5. 配置 GitHub Actions 自动部署 # 创建目录：\nPowerShell\nNew-Item -ItemType Directory -Force -Path .github\\workflows 新建 .github/workflows/hugo.yaml。时区用上海，Hugo 用 Extended，版本和本机保持一致：\nYAML\nname: Build and deploy on: push: branches: - main workflow_dispatch: permissions: contents: read pages: write id-token: write concurrency: group: pages cancel-in-progress: false defaults: run: shell: bash jobs: build: runs-on: ubuntu-latest env: DART_SASS_VERSION: 1.102.0 HUGO_VERSION: 0.165.0 TZ: Asia/Shanghai steps: - name: Checkout uses: actions/checkout@v4 with: submodules: recursive fetch-depth: 0 - name: Setup Pages id: pages uses: actions/configure-pages@v5 - name: Create a local tools directory run: mkdir -p \u0026#34;${HOME}/.local\u0026#34; - name: Install Dart Sass run: | curl -sfL --output-dir \u0026#34;${{ runner.temp }}\u0026#34; -O \u0026#34;https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz\u0026#34; tar -C \u0026#34;${HOME}/.local\u0026#34; -xf \u0026#34;${{ runner.temp }}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz\u0026#34; echo \u0026#34;${HOME}/.local/dart-sass\u0026#34; \u0026gt;\u0026gt; \u0026#34;$GITHUB_PATH\u0026#34; - name: Install Hugo run: | curl -sfL --output-dir \u0026#34;${{ runner.temp }}\u0026#34; -O \u0026#34;https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz\u0026#34; mkdir -p \u0026#34;${HOME}/.local/hugo\u0026#34; tar -C \u0026#34;${HOME}/.local/hugo\u0026#34; -xf \u0026#34;${{ runner.temp }}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz\u0026#34; echo \u0026#34;${HOME}/.local/hugo\u0026#34; \u0026gt;\u0026gt; \u0026#34;$GITHUB_PATH\u0026#34; - name: Log tool versions run: | hugo version command -v sass \u0026amp;\u0026amp; sass --version || true - name: Build run: | hugo \\ --gc \\ --minify \\ --baseURL \u0026#34;${{ steps.pages.outputs.base_url }}/\u0026#34; \\ --cacheDir \u0026#34;${{ runner.temp }}/.cache/hugo\u0026#34; - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: path: ./public deploy: needs: build runs-on: ubuntu-latest environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 说明：\n这份 workflow 跑在 GitHub 的 Linux 机器上，和本机是不是 Windows 无关 本机 hugo.exe 只用于本地预览 也可以在仓库网页 Settings → Pages 里选 GitHub Actions，再套用官方 Hugo 模板；直接提交上面这份更稳，能保证 Extended、时区和子模块都开对 6. 配置 Pages CMS 可视化后台 # 在仓库根目录新建 .pages.yml（不是 .pages.config.yml）：\nYAML\nmedia: input: static/images output: /images rename: safe categories: [image] content: - name: posts label: 博客文章 type: collection path: content/posts format: yaml-frontmatter filename: template: \u0026#34;{year}-{month}-{day}-{title}.md\u0026#34; field: create view: fields: [title, date, draft] primary: title sort: [date, title] default: sort: date order: desc fields: - name: title label: 文章标题 type: string required: true - name: date label: 发布日期 type: date - name: draft label: 草稿 type: boolean - name: description label: 文章摘要 type: text - name: tags label: 标签 type: string list: true - name: categories label: 分类 type: string list: true - name: body label: 正文 type: rich-text 这样后台会：\n把新文章存成 content/posts/2026-09-09-文章标题.md 图片存到 static/images/，正文里引用 /images/xxx.jpg body 写在 YAML front matter 下面，正好是 Hugo 要的格式 Hugo 会把 static/ 原样拷到站点根目录，所以 static/images/foo.jpg 线上地址就是 /images/foo.jpg。不要用 assets/images，除非另外做 Hugo Pipes 处理。\n7. 第一次推上去，打开 GitHub Pages # PowerShell\ncd $HOME\\alice.github.io git add . git status git commit -m \u0026#34;Initialize Hugo site with Pages CMS\u0026#34; git branch -M main git push -u origin main 如果 git push 要登录：用浏览器弹出的 GitHub 登录，或在 GitHub → Settings → Developer settings → Personal access tokens 生成 token，密码处粘贴 token。\n然后在 GitHub 网页上：\n打开仓库 → Settings → Pages Build and deployment → Source 选 GitHub Actions（改完立刻生效，没有 Save 按钮） 打开仓库的 Actions 标签，等 “Build and deploy” 变成绿色 若第一次部署弹出 github-pages environment 等待审批，点 Review deployments → Deploy 大约 1–2 分钟后访问：\ntext\nhttps://alice.github.io 能看到首页和测试文章，这一步才算发布成功。\n常见失败：\nActions 报 submodule 拉不下来：确认主题是 git submodule add 加进去的，且 workflow 里有 submodules: recursive 页面 CSS 全无 / 链接 404：baseURL 或仓库名不是 用户名.github.io 构建失败缺 hugo：检查 HUGO_VERSION 是否写对、是否下载的 hugo_extended_\u0026hellip; 8. 用网页后台发文 # 前期配置完成后，日常可以不再碰命令行。\n打开 https://app.pagescms.org Sign in with GitHub 按提示 Install GitHub App，授权刚才那个仓库（只授权这一个即可） 回到 Pages CMS，点开该仓库 若提示没有配置文件，确认根目录已经有 .pages.yml 并已推到 main 日常发文：\n左侧选 博客文章 点 Add an entry 填标题、日期、摘要、标签 正文用可视化编辑器，或直接写 Markdown 图片拖进编辑器，会自动上传到 static/images/ 点保存 → Pages CMS 向仓库提交一次 commit → 自动触发 Actions → 约 1–2 分钟网站更新 草稿：把 草稿 打开保存。Hugo 默认不发布 draft: true 的文章，适合先写后发。\n9. 可选：自定义域名 # 在域名 DNS 加一条 CNAME：blog.example.com → alice.github.io 仓库 Settings → Pages → Custom domain 填 blog.example.com 勾选 Enforce HTTPS 把 hugo.toml 里的 baseURL 改成 https://blog.example.com/ 再 push 一次 10. 之后维护 # 要做的事 在哪做 写新文章、改旧文、传图 app.pagescms.org 改网站标题、菜单、主题参数 本地改 hugo.toml 后 git push，或把该文件也配进 .pages.yml 当单文件编辑 换主题 / 升级 Hugo 本地改 submodule，或改 workflow 里的 HUGO_VERSION，再 push 看发布是否成功 GitHub 仓库 Actions 升级主题：\nPowerShell\ncd $HOME\\alice.github.io\\themes\\PaperMod git pull cd ..\\.. git add themes/PaperMod git commit -m \u0026#34;Update PaperMod\u0026#34; git push 升级本机 Hugo：下载新的 hugo_extended_*_windows-amd64.zip，覆盖 C:\\Hugo\\bin\\hugo.exe，同时改 workflow 里的 HUGO_VERSION。\n最小验收清单 # hugo version 能跑，且带 +extended git \u0026ndash;version 能跑 hugo server -D 本地能看到测试文章 git push 后 Actions 全绿 https://你的用户名.github.io 能打开 Pages CMS 能登录、能看到「博客文章」 后台新建一篇、保存，1–2 分钟后线上出现 做完这 7 步，就可以当 WordPress 的免费替代来用：静态访问、自动部署、网页后台发文，个人博客长期零成本。\n附录：Windows 常见问题 # hugo version 没有 +extended\n下错包了。删掉 hugo.exe，改下 hugo_extended_\u0026hellip;_windows-amd64.zip。\n解压后有一堆 .md 没有 hugo.exe\n下的是 Source code，不是 Assets 里的二进制 zip。\nPowerShell 执行策略报错\nhugo.exe 是独立程序，一般不触发。若 git 脚本被拦：\nPowerShell\nSet-ExecutionPolicy -Scope CurrentUser RemoteSigned 杀毒软件拦截 hugo.exe\n放行即可，这是官方发布的单文件程序。\n旧终端里仍然找不到 hugo\n改 PATH 后必须新开 PowerShell，已经打开的窗口不会自动刷新环境变量。\n","date":"September 9, 2026","externalUrl":null,"permalink":"/en/posts/%E7%94%A8-pages-cms-+-hugo-+-github-pages-%E6%90%AD%E4%B8%80%E5%A5%97%E5%85%8D%E8%B4%B9%E5%8F%AF%E8%A7%86%E5%8C%96%E5%8D%9A%E5%AE%A2/","section":"Posts","summary":"","title":"Build a Free Visual Blog with Pages CMS, Hugo, and GitHub Pages","type":"posts"},{"content":"","date":"September 9, 2026","externalUrl":null,"permalink":"/en/tags/cms/","section":"Tags","summary":"","title":"CMS","type":"tags"},{"content":"","date":"September 9, 2026","externalUrl":null,"permalink":"/en/tags/github/","section":"Tags","summary":"","title":"GitHub","type":"tags"},{"content":"","date":"September 9, 2026","externalUrl":null,"permalink":"/en/tags/github-pages/","section":"Tags","summary":"","title":"GitHub Pages","type":"tags"},{"content":"","date":"September 9, 2026","externalUrl":null,"permalink":"/en/tags/hugo/","section":"Tags","summary":"","title":"Hugo","type":"tags"},{"content":"","date":"September 9, 2026","externalUrl":null,"permalink":"/en/tags/pages-cms/","section":"Tags","summary":"","title":"Pages CMS","type":"tags"},{"content":"","date":"September 9, 2026","externalUrl":null,"permalink":"/en/tags/wordpress/","section":"Tags","summary":"","title":"WordPress","type":"tags"},{"content":"","date":"September 9, 2026","externalUrl":null,"permalink":"/en/tags/%E5%8D%9A%E5%AE%A2/","section":"Tags","summary":"","title":"博客","type":"tags"},{"content":"","date":"September 9, 2026","externalUrl":null,"permalink":"/en/categories/%E6%95%99%E7%A8%8B/","section":"Categories","summary":"","title":"教程","type":"categories"},{"content":"","date":"September 9, 2026","externalUrl":null,"permalink":"/en/tags/%E7%AC%94%E8%AE%B0/","section":"Tags","summary":"","title":"笔记","type":"tags"},{"content":"","externalUrl":null,"permalink":"/en/authors/","section":"Authors","summary":"","title":"Authors","type":"authors"},{"content":"","externalUrl":null,"permalink":"/en/posts/","section":"Posts","summary":"","title":"Posts","type":"posts"},{"content":"","externalUrl":null,"permalink":"/en/series/","section":"Series","summary":"","title":"Series","type":"series"},{"content":"","externalUrl":null,"permalink":"/archives/","section":"QiYue's Blog","summary":"archives","title":"归档","type":"page"},{"content":"","externalUrl":null,"permalink":"/search/","section":"QiYue's Blog","summary":"search","title":"搜索","type":"page"}]