本篇介绍本地预览、构建与部署上线。

返回 使用指南总览

本地预览

「预览」页提供整屏的本地预览：

  • 用 iframe 显示主题渲染后的真实博客页面（不是简化的 Markdown 预览）
  • 站点文件一有变化，预览自动刷新
  • 顶部显示当前访问地址与运行状态

控制项

按钮 作用
包含草稿 勾选后草稿也会被渲染（切换会自动重启预览使其生效）
启动预览 启动本地服务
停止 停止服务
浏览器打开 用系统默认浏览器打开预览地址
刷新 手动刷新 iframe

预览使用随机可用端口（从 4000 起找空闲端口），不会和别的服务冲突。

关闭站点或切换站点时，预览会自动停止。

构建与部署

「发布」页有三个操作：

操作 对应命令 说明
生成静态页面 hexo generate 把源码渲染成 public/ 下的 HTML
部署上线 先 generate 再 hexo deploy 推送到远端仓库
清理缓存 hexo clean 删除 public/ 与缓存，问题排查时用

顶部会显示当前部署目标（仓库地址 + 分支），未配置时提示你去设置页填写。

部署会自动先生成

点「部署上线」后，流程是：

  1. 先执行一次 hexo generate —— 确保推送的是最新内容，而不是上次生成的旧产物
  2. 生成成功后才执行 hexo deploy 推送

为什么这样做：hexo deploy 本身不会自动生成。如果只跑 deploy，推上线的是 public/ 目录里已有的内容 —— 你新写的文章如果没手动生成过，就不会被推上去。

部署失败会被识别

这是 HexoDeck 相比手动部署的一个重要改进：

hexo deploy 在 git 推送失败时不会返回非零退出码，所以命令行里看起来是「成功」，实际上什么都没推上去 —— 这种「假成功」很容易让人困惑。

HexoDeck 会从命令输出里识别真正的失败原因并明确报错：

情况 提示
仓库不存在 远程仓库不存在，请检查仓库地址
认证失败 认证失败，请检查 Git 凭据
推送被拒 推送被远端拒绝
分支为空 分支配置有误（deploy.branch 可能为空）
网络问题 无法访问远程仓库，请检查网络与权限
插件缺失 未安装部署插件（如 hexo-deployer-git）

失败时不会给出「部署完成」的假提示，并且日志区能看到完整输出。

运行日志

页面底部的日志区实时显示每条命令的输出，可用于排查问题。日志支持一键清空，同时也会落地到日志文件（「设置 → 应用」可打开日志文件夹）。

首次部署 GitHub Pages 的完整流程

以「用户名.github.io」仓库为例：

1. 创建仓库

在 GitHub 创建一个名为 用户名.github.io 的公开仓库。

2. 配置部署信息

在「设置 → 部署」里填：

  • 部署方式：Git
  • 仓库地址：https://github.com/用户名/用户名.github.io.git
  • 分支：main（点快捷填入按钮）

3. 确认插件

如果提示缺少 hexo-deployer-git，点「一键安装」。

4. 执行部署

回到「发布」页，点「部署上线」。

5. 首次可能需要输入凭据

第一次推送时 git 会要求认证。推荐用 Personal Access Token 代替密码：

  1. GitHub → Settings → Developer settings → Personal access tokens
  2. 生成一个带 repo 权限的 token
  3. 推送时用户名填 GitHub 用户名，密码填这个 token

或者改用 SSH 地址（[email protected]:用户名/仓库.git）并配置好 SSH 密钥。

6. 等待站点生效

推送成功后，GitHub Pages 需要一两分钟构建。之后访问 https://用户名.github.io 即可看到你的博客。

排查部署问题

部署后网站没更新？

  1. 检查日志区有没有报错
  2. 确认部署目标仓库地址与分支正确
  3. 登录 GitHub 看仓库最近的 commit 时间，确认推送是否真的成功

推送一直失败？

  • 检查网络能否访问 GitHub
  • 检查凭据是否有效（token 可能过期）
  • 确认仓库存在且你有写权限

想重新开始？

点「清理缓存」清除 public/ 和缓存，再点「生成静态页面」全量重建。

下一步：常见问题 → 常见问题