cocosCreator

Hexo文章上传指令操作

Hexo 博客从安装到本地预览+线上部署完整教程

1
2
3
4
5
6
7
8
9
10
# 1. 清理缓存
hexo clean

# 2. 生成最新静态文件
hexo g
# 3. 临时访问
hexo s -p 3000  # 访问地址：http://localhost:3000

# 4. 推送部署到 GitHub（核心命令）
hexo d  # 或 hexo deploy
1
2
3
4
5
6
7
8
9
10
11
本文详细记录 Hexo 博客的安装配置、本地预览及线上部署全流程，适用于 macOS（Apple 芯片）系统，Windows/Linux 可参考适配对应路径，新手可直接按步骤操作。

一、前置准备

1. 安装 Node.js
Hexo 基于 Node.js 开发，需先安装 Node.js（自带 npm 包管理器）：
- 下载地址：[Node.js 官网](https://nodejs.org/)
- 安装要求：推荐下载 LTS 长期支持版（如 18.x 或 20.x），安装后自动配置环境变量
- 验证安装：终端执行以下命令，输出版本号即成功
  node -v  # 输出示例：v18.17.0
  npm -v   # 输出示例：9.6.7

1. 全局安装 Hexo 脚手架

终端执行以下命令，全局安装 Hexo 核心工具：

1
npm install -g hexo-cli

安装成功提示：

  • changed 53 packages in 686ms
14 packages are looking for funding
  run `npm fund` for details

    1
    2
    3
    4
    5
    6
    7
    8
    9

    ### 2. 配置 zsh 环境变量（解决 "command not found: hexo"）

    安装后若终端提示找不到 hexo 命令，需配置环境变量（macOS Apple 芯片专属路径）：

    查看 npm 全局前缀路径（终端执行）：

    ```bash
    npm config get prefix

  • 输出结果（Apple 芯片默认）：/opt/homebrew

编辑 zsh 配置文件：

1
2
# 打开配置文件（无则自动创建）
touch ~/.zshrc && open ~/.zshrc

在文件末尾添加以下内容（直接复制）：

1
export PATH="/opt/homebrew/bin:$PATH"

生效配置并验证：

1
2
3
4
5
# 让配置立即生效
source ~/.zshrc

# 验证 Hexo 是否安装成功（输出版本号即成功）
hexo -v
  • 成功输出示例：
1
2
3
hexo-cli: 4.3.0
node: 18.17.0
os: darwin arm64

三、Hexo 本地预览操作

1. 初始化 Hexo 博客（首次操作）

  1. 终端进入需存放博客的目录（如桌面）：
1
cd ~/Desktop  # 示例：进入桌面

初始化博客文件夹（替换 my-hexo-blog 为自定义博客名）：

1
hexo init my-hexo-blog

进入博客根目录：

1
cd my-hexo-blog

2. 本地预览核心命令（按顺序执行）

所有命令需在 博客根目录 执行：

（1）清理缓存（可选但推荐）

清除旧版静态文件和缓存，避免冲突：

1
hexo clean
  • 成功输出：INFO Deleted database. INFO Deleted public folder.

（2）生成静态文件

将 Markdown 文章、主题模板编译为 HTML/CSS/JS 静态文件（生成到 public 文件夹）：

1
hexo g  # 全称 hexo generate，简写 g 更便捷
  • 成功输出：INFO Generated x pages（x 为生成的页面数量）

（3）启动本地服务器

启动内置服务器，实现本地预览：

1
hexo s  # 全称 hexo server，简写 s

成功输出：

1
2
INFO  Start processing
INFO  Hexo is running at http://localhost:4000 . Press Ctrl+C to stop.

3. 本地预览访问

打开浏览器，输入地址 http://localhost:4000，即可看到 Hexo 默认博客页面。

  • 实时预览：修改文章、配置或主题后，刷新浏览器即可看到更新
  • 停止服务器：终端按 Ctrl + C 组合键

4. 实用补充指令

（1）指定端口启动（避免端口占用）

若 4000 端口被占用，可指定其他端口（如 3000）：

1
hexo s -p 3000  # 访问地址：http://localhost:3000

（2）一键执行清理 + 生成 + 启动

无需分步输入，用 && 连接指令：

1
hexo clean && hexo g && hexo s

（3）调试模式启动（排查问题）

预览异常时，开启调试模式查看详细日志：

1
hexo s --debug

四、Hexo 线上部署（hexo d 命令使用）

hexo d 是 hexo deploy 的简写，用于将本地静态文件推送到远程平台（如 GitHub Pages），实现线上访问。

1. 安装部署插件（必须）

在博客根目录执行，安装 Git 部署插件：

1
npm install hexo-deployer-git --save

2. 配置远程部署平台（以 GitHub Pages 为例）

（1）准备 GitHub 仓库

  1. 登录 GitHub，新建仓库，仓库名必须为：你的GitHub用户名.github.io（如 xxx.github.io）
  2. 仓库页面点击「Code」，复制仓库 HTTPS/SSH 地址（如 https://github.com/xxx/xxx.github.io.git）

（2）配置 Hexo 部署信息

  1. 打开博客根目录的 _config.yml 文件（Hexo 主配置文件）：
1
open _config.yml

拉到文件末尾，找到或新增 deploy 节点，添加以下配置（替换为你的信息）：

1
2
3
4
5
deploy:
  type: git  # 部署类型：Git
  repo: https://github.com/你的GitHub用户名/你的GitHub用户名.github.io.git  # 复制的仓库地址
  branch: main  # 部署分支（GitHub Pages 默认 main 分支）
  message: "Hexo deploy: {{ now('YYYY-MM-DD HH:mm:ss') }}"  # 自动添加部署时间（可选）
  • 注意：YAML 格式要求冒号后面必须加空格！

3. 执行部署命令

配置完成后，在博客根目录按以下顺序执行：

1
2
3
4
5
6
7
8
# 1. 清理缓存
hexo clean

# 2. 生成最新静态文件
hexo g

# 3. 推送部署到 GitHub（核心命令）
hexo d  # 或 hexo deploy

部署成功标志

终端输出以下信息且无报错：

1
2
3
4
5
6
INFO  Deploying: git
INFO  Clearing .deploy_git folder...
INFO  Copying files from public folder...
INFO  Commit with message: Hexo deploy: 2025-11-05 16:30:00
INFO  Pushing to https://github.com/xxx/xxx.github.io.git
INFO  Deploy done: git

4. 访问线上博客

部署成功后，等待 1-5 分钟，浏览器访问 https://你的GitHub用户名.github.io（如 https://xxx.github.io），即可看到线上博客。

五、常见问题排查

1. 终端提示 “command not found: hexo”

  • 原因：环境变量配置错误或未生效
  • 解决：重新执行 source ~/.zshrc，或检查 ~/.zshrc 中路径是否为 /opt/homebrew/bin

2. hexo d 报错 “No repository defined”

  • 原因：_config.yml 中 deploy 节点的 repo 地址未配置或格式错误
  • 解决：检查 repo 地址是否正确（含 .git 后缀），确保冒号后加空格

3. 部署成功后访问 404

  • 检查 GitHub 仓库名是否为 用户名.github.io（严格区分大小写）
  • 进入仓库「Settings → Pages」，确认部署分支为 main 且状态为「已启用」

4. 推送时权限不足

  • 方案 1：改用 SSH 地址部署（需提前配置 GitHub SSH 密钥）
  • 方案 2：HTTPS 地址部署时，输入 GitHub 个人访问令牌（替代密码），令牌需勾选 repo 权限

六、总结

1. 核心流程

安装 Node.js → 安装 Hexo → 配置环境变量 → 本地预览 → 线上部署

2. 常用命令速查

功能 命令
初始化博客 hexo init 博客名
清理缓存 hexo clean
生成静态文件 hexo g（全称 hexo generate）
本地预览 hexo s（全称 hexo server）
线上部署 hexo d（全称 hexo deploy）
一键部署 hexo clean && hexo g && hexo d

说明：按本文步骤操作后，即可实现 Hexo 博客的本地开发预览和线上公开访问。如需部署到 Gitee Pages、Netlify 等其他平台，可参考对应平台的仓库配置规则修改 _config.yml 中的 deploy 节点。

plaintext

1
2
3
4
5
6
7
验证文件有效性
生成 `.md` 文件后，可通过以下方式确认：
1. 用 Typora、VS Code（安装 Markdown 插件）、Obsidian 等编辑器打开
2. 查看格式：标题层级、代码块高亮、表格、列表是否正常显示
3. 所有命令可直接复制使用，无需额外修改

按上面的方法操作，你会得到一个 **标准、可编辑、可分享** 的 `.md` 文档，完全满足下载使用的需求～