Hexo Admin 配置与后台操作全流程指南（2023 年 10 月 1 日）
Hexo Admin 详细配置+后台操作指南（从安装到发布全流程）
这份指南会帮你彻底搞定 Hexo Admin 的配置、安全设置、文章编辑和一键部署，全程可视化操作，完全替代命令行，新手也能快速上手。
一、前期准备
- 本地已安装 Node.js 和 Hexo 环境（之前能正常用 hexo g -d 推送，说明已满足）。
- 进入本地 Hexo 博客根目录（不是 source 或其他子目录），所有命令都在此目录执行。
- 确保 Hexo 已配置好部署目标（如 GitHub Pages、Vercel），部署命令 hexo clean && hexo g -d 能正常运行。
二、核心配置步骤（5分钟搞定）
- 安装 Hexo Admin 插件
打开终端，在 Hexo 根目录执行安装命令：
npm install --save hexo-admin
- 若安装失败（如网络超时），可切换 npm 镜像后重试：
npm config set registry https://registry.npm.taobao.org
npm install --save hexo-admin
- 启动本地服务+访问后台
安装完成后，启动 Hexo 本地服务（会自动加载 Admin 后台）：
hexo server # 或简写 hexo s，无需加 -d 也能访问后台
启动成功后，打开浏览器访问：http://localhost:4000/admin/，即可进入 Hexo Admin 可视化后台（默认无需登录，本地访问安全）。
- 安全设置（可选但推荐）
如果需要在局域网内访问后台，或担心本地服务被他人误操作，可设置登录密码：
方法1：自动生成配置（推荐，无需手动算哈希）
- 访问 http://localhost:4000/admin/，点击顶部导航栏的 Settings（设置）。
找到 Set up Authentication（设置认证），填写：
- Username：自定义用户名（如你的博客名）。
- Password：想要设置的登录密码。
- Secret：任意长字符串（越复杂越好，用于加密会话，如 abc123xyz789xxx）。
- 下滑找到生成的 YAML 代码，复制全部内容。
- 打开 Hexo 根目录的 _config.yml 文件，粘贴到文件末尾，保存并关闭。
- 重启 Hexo 服务（ctrl+c 停止后，重新执行 hexo s），再次访问后台需输入用户名和密码。
方法2：手动配置（需计算密码哈希）
- 终端执行 npm install bcrypt-nodejs，安装哈希生成工具。
- 输入 node 进入 Node 环境，执行以下命令（替换 your_password 为你的密码）：
const bcrypt = require('bcrypt-nodejs');
bcrypt.hashSync('your_password'); // 执行后会输出密码哈希值
- 复制哈希值，在 _config.yml 末尾添加：
admin:
username: 你的用户名
password_hash: 刚才生成的哈希值
secret: 任意复杂字符串（如 asdfghjkl123456）
- 重启 Hexo 服务即可生效。
- 解决一键部署报错（关键步骤）
首次点击后台“Deploy”（部署）按钮时，可能会出现 Config value "admin.deployCommand" not found 或 deploy Error: spawn UNKNOWN 报错，按以下步骤解决：
步骤1：创建部署脚本文件
Windows 系统：
- 在 Hexo 根目录新建文本文件，重命名为 hexo-deploy.bat（注意后缀是 .bat，不是 .txt）。
- 打开文件，写入部署命令：
hexo clean && hexo g && hexo d
- 保存文件（确保编码为 UTF-8）。
Mac/Linux 系统：
- 终端进入 Hexo 根目录，执行命令创建脚本：
touch hexo-deploy.sh && chmod a+x hexo-deploy.sh
- 用编辑器打开 hexo-deploy.sh，写入：
!/bin/bash
hexo clean && hexo g && hexo d
- 保存文件。
步骤2：配置部署命令路径
打开 Hexo 根目录的 _config.yml，在之前的 admin 配置下添加 deployCommand，指向刚才创建的脚本：
admin:
username: 你的用户名
password_hash: 你的密码哈希值
secret: 你的复杂字符串
deployCommand: ./hexo-deploy.bat # Windows 用这个
# deployCommand: ./hexo-deploy.sh # Mac/Linux 用这个
步骤3：修复 Windows 部署报错（仅 Windows 需做）
若执行部署仍报错 deploy Error: spawn UNKNOWN，按以下操作修改：
- 打开 Hexo 根目录的 node_modules/hexo-admin/deploy.js 文件。
- 找到代码 var proc = spawn(command, (message), {detached: true});。
- 替换为：
var proc = spawn((process.platform === "win32" ? "hexo.cmd" : "hexo"), ('d'));
- 保存文件，重启 Hexo 服务即可正常部署。
三、后台操作全流程（可视化管理文章）
- 新建文章
- 访问 http://localhost:4000/admin/，点击左侧 New Post（新建文章）。
填写核心信息：
- Title：文章标题（如“Hexo Admin 使用指南”）。
- Slug：文章路径（可选，默认是标题的英文小写，如“hexo-admin-user-guide”）。
- Date：发布时间（默认当前时间，可手动修改）。
- Tags：标签（输入后按回车添加，支持多个）。
- Categories：分类（支持一级/二级分类，如“技术 > 博客搭建”）。
- 下方编辑区写文章内容，支持 Markdown 语法，右侧实时预览效果。
- 写完后点击右上角 Save（保存），会自动生成 .md 文件到 source/_posts 目录（草稿状态）；点击 Publish（发布），会直接标记为已发布文章。
- 编辑/删除已有文章
- 后台左侧 Posts 列表中，会显示所有已发布文章，点击文章标题即可进入编辑界面。
- 编辑完成后点击 Update（更新），会自动覆盖原文件。
- 若要删除文章，点击编辑界面右上角的 Delete（删除），确认后即可删除对应的 .md 文件。
- 管理分类和标签
- 点击后台顶部 Categories，可添加/编辑/删除分类，支持拖拽调整顺序。
- 点击 Tags，可管理所有标签，支持批量删除或修改标签名称。
- 一键部署博客
- 文章编辑完成（发布或更新后），点击后台顶部 Deploy（部署）。
- 后台会显示部署日志，若最后出现 “Deploy successful” 或类似提示，说明部署成功。
- 等待几分钟后，访问你的博客域名（如 https://zhang-curry.github.io/），即可看到更新后的内容。
- 图片上传与插入（实用技巧）
- 在编辑区直接复制图片（本地图片或网络图片），粘贴到内容中，Hexo Admin 会自动将图片保存到 source/images 目录，并生成正确的图片路径。
- 若 Windows 系统粘贴后图片显示破裂，手动删除图片路径中多余的斜杠（如将 //images/xxx.jpg 改为 /images/xxx.jpg）即可正常显示。
四、汉化后台（可选，中文用户友好）
默认后台是英文界面，可通过替换文件实现汉化：
- 下载汉化版 bundle.js 文件：访问 https://gitlab.com/KINGWDY/tgbb/-/raw/main/bundle.js ，右键“另存为”保存到本地。
- 打开 Hexo 根目录的 node_modules/hexo-admin/www/ 文件夹，找到原有的 bundle.js 文件，备份后删除。
- 将下载的汉化版 bundle.js 复制到该文件夹中。
- 刷新后台页面，即可看到中文界面（如“新建文章”“部署”“设置”等）。
五、注意事项
- Hexo Admin 仅在本地 hexo server 运行时可用，关闭服务后后台无法访问，且不会被部署到远程服务器（安全无隐患）。
- 每次修改 _config.yml 或 deploy.js 后，需重启 hexo server 才能生效。
- 若后台无法访问，检查端口是否被占用（默认 4000 端口），可换端口启动：hexo s -p 4001，然后访问 http://localhost:4001/admin/。
需要我帮你生成一份 “Hexo Admin 常见问题排查手册” 吗？包含安装失败、部署报错、图片无法显示等问题的快速解决方案，遇到问题可直接查阅。
评论 (0)