Hexo网站部署详细流程操作

Hexo 网站 0 到 1 部署详细流程操作指南本文档详细记录从零开始搭建并部署 Hexo 博客网站到线上服务器的完整流程涵盖环境准备、本地初始化、主题配置、内容编写、构建发布、服务器部署及维护更新等所有环节。文章目录Hexo 网站 0 到 1 部署详细流程操作指南一、环境准备1.1 安装 Node.js1.2 验证 Node.js 安装1.3 安装 Git1.4 安装 Hexo 命令行工具1.5 配置 npm 国内镜像可选加速下载二、本地初始化 Hexo 项目2.1 选择工作目录2.2 初始化博客项目2.3 验证初始化结果三、主题安装与配置4.1 选择主题4.2 安装主题这里以 Butterfly 为例4.3 启用主题4.4 安装主题依赖插件4.5 主题级配置四、站点配置五、写作与内容管理5.1 创建新文章5.2 Front-matter 字段说明5.3 创建草稿5.4 创建页面5.5 插入图片方式一放在 source/images/ 下方式二启用 post_asset_folder六、本地预览与调试七、生成静态文件八、部署方案选择九、方案 AGitHub Pages 部署9.1 创建仓库9.2 安装部署插件9.3 配置 _config.yml9.4 配置 SSH 密钥推荐避免每次输入密码9.5 一键部署9.6 开启 GitHub Pages十、方案 BVPS / 云服务器部署10.1 准备服务器10.2 服务器初始化10.3 配置 Git 仓库用于接收推送10.4 本地配置 SSH 免密登录10.5 本地 _config.yml 配置10.6 配置 Nginx10.7 本地发布十一、方案 C宝塔面板部署我使用的11.1 安装宝塔面板11.2 服务器安装 Git11.3 创建 Git 用户并配置 SSH 免密登录11.4 本地电脑生成 SSH 密钥如已有可跳过11.5 服务器端配置公钥11.6 本地验证免密登录11.7 创建 Git 裸仓库与自动部署钩子11.8 初始化裸仓库11.9 配置 post-receive 钩子11.10 宝塔面板配置网站十二、域名绑定与 HTTPS12.1 域名解析12.2 申请 SSL 证书方式一Lets Encrypt免费、自动续期方式二Cloudflare 代理推荐12.3 强制 HTTPS十三、CI/CD 自动化部署13.1 GitHub Actions 自动构建13.2 配置 GitHub Pages13.3 推送即部署十四、备份与维护14.1 源码版本控制14.2 推送源码到 GitHub14.3 多设备同步14.4 数据库备份如有评论系统14.5 升级 Hexo 与主题十五、常见问题排查15.1 hexo server 端口被占用15.2 部署后页面 40415.3 样式丢失 / 资源 40415.4 中文链接乱码15.5 Git 部署报错 Deployer not found: git15.6 文章不显示15.7 主题配置不生效附录常用命令速查表部署流程总览一、环境准备Hexo 基于 Node.js 运行部署到远端服务器通常还需要 Git。安装前请确认操作系统位数与版本。1.1 安装 Node.js访问官网https://nodejs.org/zh-cn/下载LTS 长期支持版建议 ≥ 18.xWindows 用户下载.msi安装包按向导下一步即可macOS 用户可使用 Homebrewbrew install nodeLinux 用户可使用包管理器或 nvmcurl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh|bashnvminstall--lts1.2 验证 Node.js 安装打开终端Windows 使用 PowerShell 或 Git Bash执行node-vnpm-v能正常显示版本号即安装成功。1.3 安装 GitWindows下载 https://git-scm.com/download/win 并安装macOSbrew install gitLinuxDebian/Ubuntusudo apt-get install git验证git--version1.4 安装 Hexo 命令行工具npminstall-ghexo-cli验证hexo-v如遇权限问题Linux/macOS可在前面加sudo或推荐使用 nvm 管理 Node 版本以避免全局权限问题。1.5 配置 npm 国内镜像可选加速下载npmconfigsetregistry https://registry.npmmirror.com二、本地初始化 Hexo 项目2.1 选择工作目录桌面直接创建Hexo_btt_web文件夹点击进入推荐空间不大只有323 MB左右这里需要记住目录如果忘记可以进行以下操作复制路径按win x点击左下角出现的终端使用cd进入目录按回车键方便下一步执行命令提示这里ctrl v可能没有用点击鼠标右键即可粘贴目录路径2.2 初始化博客项目使用命令创建 butterfly 文件夹mkdirbutterfly如图依次执行如下命令hexo init butterflycdbutterflynpminstall如图进入butterfly文件夹hexo init会自动拉取 Hexo 默认模板并创建以下目录结构butterfly/ ├── _config.yml # 站点主配置文件 ├── package.json # 项目依赖描述 ├── scaffolds/ # 文章模板 ├── source/ # 资源目录文章、图片等 │ ├── _drafts/ # 草稿 │ └── _posts/ # 已发布文章 └── themes/ # 主题目录2.3 验证初始化结果hexo server# 或简写hexo s浏览器访问 http://localhost:4000 看到默认 Hello World 页面如下图即成功。按Ctrl C退出。退出后如下图三、主题安装与配置4.1 选择主题常见流行主题Nexthttps://theme-next.js.org/Butterflyhttps://butterfly.js.org/Fluidhttps://hexo.fluid-dev.com/Materyhttps://github.com/blinkfox/hexo-theme-matery4.2 安装主题这里以 Butterfly 为例npminstallhexo-theme-butterfly--save或通过 Git 克隆便于自定义gitclone-bmaster https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly提示这里需要访问 GitHub 才能克隆可能会中断可以开启 GitHub 极简访问4.3 启用主题在文件夹butterfly中选择_config.yml鼠标右键点击 在笔记本中编辑 或者使用 VS code 编辑。为了方便和观察我这里使用 VS code编辑站点_config.yml在VS code 按快捷键ctrl h查找 theme:theme:butterfly4.4 安装主题依赖插件Butterfly 推荐安装以下插件npminstallhexo-renderer-pug hexo-renderer-stylus--save如图4.5 主题级配置将_config.landscape.yml重命名为_config.butterfly.yml主题目录官方推荐_config.yml和_config.butterfly.yml这两个文件夹放在根目录。不需要移到 themes 文件夹中。因为Hexo 在生成博客时会自动将这两个文件进行合并。如果两个文件中存在相同的配置项Hexo 会优先使用 _config.yml 中的配置。这里推荐直接修改_config.yml文件按需修改导航菜单、社交链接、评论系统、统计代码等。四、站点配置在_config.yml里找到并编辑以下内容同时重点关注以下字段# 站点信息title:Hexo BTT Blog# 网站标题subtitle:个人技术博客# 副标题description:记录学习与生活# 描述用于 SEOkeywords:hexo,btt,blog# 关键词author:Your Name# 作者language:zh-CN# 语言timezone:Asia/Shanghai# 时区# URL 配置url:https://www.example.com# 最终上线域名permalink::year/:month/:day/:title/# 文章链接格式permalink_defaults:pretty_urls:trailing_index:truetrailing_html:true# 部署配置以 git 为例deploy:type:gitrepo:gitgithub.com:yourname/yourname.github.io.gitbranch:mainYAML 文件对缩进敏感必须使用空格而非 Tab冒号后必须有一个空格。五、写作与内容管理5.1 创建新文章hexo new我的第一篇文章# 简写hexo n我的第一篇文章文件生成于source/_posts/我的第一篇文章.md5.2 Front-matter 字段说明文章头部使用 YAML 格式的元数据---title:我的第一篇文章#作用文章的标题。它会显示在文章页面的顶部、首页的文章列表中以及浏览器的标签页上。date:2026-08-16 13:46:33#作用文章的创建时间。Hexo 会根据这个时间对文章进行排序默认最新的在最前面#并在文章页面显示“发布于2026-08-16”。tags:-Hexo-教程#tags:(标签)#作用用于对文章进行多维度、细粒度的标注。你可以把它理解为文章的“关键词”。#特点标签没有层级关系一篇文章可以打多个标签。#这个例子中这篇文章同时被打上了 Hexo 和 教程 两个标签。#读者点击这些标签就能看到所有带有该标签的文章。categories:-技术-建站#categories: (分类)#作用用于对文章进行宏观的、系统性的归类。它具有层级和顺序性。#特点在你的例子中技术 是一级分类建站 是 技术 下的二级分类即技术 建站。#这与标签有本质区别categories: [建站, 技术] 和 categories: [技术, 建站] 代表的是不同的分类路径。cover:/images/cover.jpg#作用文章的封面图。它会显示在首页的文章卡片上。设置一个好看的封面图能大大增加读者的点击欲望。#注意这里的 /images/cover.jpg 是相对路径通常指向你博客根目录下 source/images/ 文件夹里的图片。#你也可以使用完整的图床外链如 https://...。top:false# 是否置顶#作用是否置顶。这是 Butterfly 主题的扩展功能。#说明如果设置为 true这篇文章会强制显示在首页列表的最顶端无论它的 date 是什么时候。#这对于“置顶公告”或“博客导航”非常有用。这里设置为 false表示按正常时间排序。comments:true# 是否开启评论#作用是否开启评论功能。这也是 Butterfly 主题的扩展功能。#说明设置为 true 时文章底部会加载你在主题配置文件中设置的评论系统如 Gitalk, Waline 等。#如果你写了一篇纯记录性质的文章不想让别人评论可以将其改为 false该文章的评论区就会被隐藏。---5.3 创建草稿hexo new draft未完成的想法会创建到目录\butterfly\source\_drafts\未完成的想法.md如图草稿默认不会发布到线上。发布草稿hexo publish未完成的想法会移动到目录\butterfly\source\_posts\未完成的想法.md原来目录的草稿会自动销毁。如下图5.4 创建页面hexo new page about# 关于页hexo new page tags# 标签页hexo new page categories# 分类页页面文件生成于source/name/index.md如下图5.5 插入图片方式一放在source/images/下提示一般images文件夹是没有的需要手动创建在文章中使用!感叹号是 Markdown 中用来声明“这是一个图片”的标志。[]方括号内用于填写图片的替代文本Alt Text。当图片因为网络问题无法加载或者用户使用屏幕阅读器时会显示这里的文字。代码中这里是空的表示没有设置替代文本。()圆括号内填写的是图片的路径或链接。方式二启用 post_asset_folder修改_config.ymlpost_asset_folder:true执行hexo new时会自动生成同名资源目录文章中引用{% asset_img pic.png 描述 %}六、本地预览与调试# 启动本地服务器默认 4000 端口hexo server# 指定端口hexo server-p5000# 实时调试修改文件自动刷新需安装 hexo-browsersyncnpminstallhexo-browsersync--savehexo server--debug访问 http://localhost:4000 查看效果。七、生成静态文件# 清理缓存与已生成文件hexo clean# 生成静态文件到 public/ 目录hexo generate# 简写hexo g# 生成并立即部署hexo g-d# 或hexo d-g生成结果位于public/目录这就是要部署到服务器的全部静态资源。八、部署方案选择根据服务器与需求选择方案适用场景成本难度GitHub Pages个人博客、流量小免费低VPS / 云服务器需要完全控制付费中宝塔面板BT Panel可视化管理、新手友好付费低Vercel / Netlify现代 CI/CD、全球 CDN免费起步低九、方案 AGitHub Pages 部署9.1 创建仓库登录 GitHub新建仓库仓库名必须为你的用户名.github.io例如zhangsan.github.io类型选 Public9.2 安装部署插件npminstallhexo-deployer-git--save9.3 配置 _config.ymldeploy:type:gitrepo:https://github.com/用户名/用户名.github.io.gitbranch:mainmessage:Site updated: {{ now | date(YYYY-MM-DD HH:mm:ss) }}9.4 配置 SSH 密钥推荐避免每次输入密码# 生成密钥回车全部默认ssh-keygen-ted25519-Cyour_emailexample.com# 查看公钥cat~/.ssh/id_ed25519.pub将公钥添加到 GitHubSettings → SSH and GPG keys → New SSH key。测试连接ssh-Tgitgithub.com9.5 一键部署hexo cleanhexo g-d9.6 开启 GitHub Pages进入仓库 → Settings → PagesSource 选择Deploy from a branchBranch 选择main/root保存后等待 1~2 分钟访问https://用户名.github.io十、方案 BVPS / 云服务器部署10.1 准备服务器推荐阿里云、腾讯云、AWS、Vultr 等轻量服务器系统Ubuntu 22.04 LTS配置1 核 1G 起步即可10.2 服务器初始化# 更新系统sudoaptupdatesudoaptupgrade-y# 安装 Git 与 Nginxsudoaptinstallgitnginx-y# 创建专用用户可选sudoadduser blogsudopasswdblog10.3 配置 Git 仓库用于接收推送# 创建裸仓库sudomkdir-p/var/repo/blog.gitsudogitinit--bare/var/repo/blog.git# 创建网站根目录sudomkdir-p/var/www/hexo# 配置 git hook 自动部署sudovim/var/repo/blog.git/hooks/post-receive写入以下内容#!/bin/bashgit--work-tree/var/www/hexo --git-dir/var/repo/blog.git checkout-f赋权sudochmodx /var/repo/blog.git/hooks/post-receivesudochown-Rblog:blog /var/repo/blog.git /var/www/hexo10.4 本地配置 SSH 免密登录# 将本地公钥追加到服务器ssh-copy-id blogyour_server_ip10.5 本地 _config.yml 配置deploy:type:gitrepo:blogyour_server_ip:/var/repo/blog.gitbranch:master10.6 配置 Nginxsudovim/etc/nginx/conf.d/hexo.conf写入server { listen 80; server_name your_domain.com; root /var/www/hexo; index index.html index.htm; location / { try_files $uri $uri/ /index.html; } location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ { expires max; log_not_found off; } gzip on; gzip_types text/plain text/css application/json application/javascript; }重载 Nginxsudonginx-tsudosystemctl reload nginx10.7 本地发布hexo cleanhexo g-d推送完成后服务器/var/www/hexo会自动更新静态文件。十一、方案 C宝塔面板部署我使用的宝塔面板提供可视化 Web 界面适合不熟悉命令行的用户。11.1 安装宝塔面板登录服务器执行以 Ubuntu 为例wget-Oinstall.sh https://download.bt.cn/install/install-ubuntu_6.0.shsudobashinstall.sh ed8484bec安装完成后记录面板地址、账号、密码。11.2 服务器安装 Git通过宝塔面板的 终端 操作先确认 Git 是否已安装git--version如果未安装执行yuminstall-ygit11.3 创建 Git 用户并配置 SSH 免密登录服务器端创建用户# 创建 git 用户addusergit# 设置密码passwdgit# 赋予 sudo 权限chmod740/etc/sudoersvim/etc/sudoers# 在 root ALL(ALL) ALL 下方添加# git ALL(ALL) ALL# 保存退出后恢复权限chmod400/etc/sudoers11.4 本地电脑生成 SSH 密钥如已有可跳过ssh-keygen-trsa# 一路回车公钥位置WindowsC:\Users\你的用户名\.ssh\id_rsa.pubMac/Linux~/.ssh/id_rsa.pub打开id_rsa.pub复制全部内容。11.5 服务器端配置公钥sugitmkdir-p~/.sshchmod700~/.sshtouch~/.ssh/authorized_keyschmod600~/.ssh/authorized_keysvim~/.ssh/authorized_keys# 粘贴公钥内容:wq 保存退出11.6 本地验证免密登录sshgit你的服务器公网IP无需密码即可登录说明配置成功输入 exit 退出。11.7 创建 Git 裸仓库与自动部署钩子回到 root 用户执行以下操作创建目录# Git 仓库目录接收推送mkdir-p/home/git/repochown-Rgit:git /home/git/repochmod-R755/home/git/repo# 网站目录Nginx 指向这里mkdir-p/www/hexo_webchown-Rgit:git /www/hexo_webchmod-R755/www/hexo_web11.8 初始化裸仓库cd/home/git/repogitinit--bareblog.gitchowngit:git-Rblog.git11.9 配置 post-receive 钩子vim/home/git/repo/blog.git/hooks/post-receive粘贴以下内容#!/bin/bashgit--work-tree/www/hexo_web --git-dir/home/git/repo/blog.git checkout-f保存退出后赋予执行权限chmodx /home/git/repo/blog.git/hooks/post-receive每次本地hexo d推送时钩子会自动将最新静态文件检出到/www/hexo_web。11.10 宝塔面板配置网站进入宝塔面板 → 网站 → 添加站点配置项填写内容域名你的域名或公网 IP根目录/www/hexo_webFTP不创建数据库不创建PHP 版本纯静态点击提交。确认 Nginx 配置在站点设置 → 配置文件 中确认 root 指向正确server{listen80;server_name 你的域名或IP;root /www/hexo_web;index index.html index.htm;}如需 HTTPS在站点设置 → SSL 中申请 Let’s Encrypt 免费证书并开启强制跳转。本地 Hexo 配置与部署打开本地 Hexo 博客根目录下的 _config.yml配置 deploydeploy: type:gitrepository: git你的服务器公网IP:/home/git/repo/blog.git branch: master执行部署hexo clean hexo g hexo d如果提示ERROR Deployer not found: git先安装npminstallhexo-deployer-git--save在浏览器输入你的 服务器公网 IP 或 域名即可看到 Hexo 博客页面。以后每次写完文章只需执行hexo cleanhexo ghexo d如果整行命令执行不了就一个个执行hexo clean hexo g hexo d博客就会自动同步到服务器。十二、域名绑定与 HTTPS12.1 域名解析在域名服务商如阿里云、Cloudflare控制台添加 A 记录类型主机记录记录值A服务器公网 IPAwww服务器公网 IPCNAMEwwwexample.com等待 10 分钟左右生效可用ping your_domain.com测试。12.2 申请 SSL 证书方式一Let’s Encrypt免费、自动续期sudoaptinstallcertbot python3-certbot-nginx-ysudocertbot--nginx-dyour_domain.com-dwww.your_domain.com按提示完成certbot 会自动修改 Nginx 配置并开启 HTTPS。方式二Cloudflare 代理推荐将域名 NS 修改为 Cloudflare在 Cloudflare 添加站点SSL/TLS 模式选 “Full” 或 “Full (strict)”开启 “Always Use HTTPS”12.3 强制 HTTPSNginx 配置中追加server { listen 80; server_name your_domain.com www.your_domain.com; return 301 https://$host$request_uri; }十三、CI/CD 自动化部署13.1 GitHub Actions 自动构建在仓库根目录创建.github/workflows/deploy.ymlname:Deploy Hexoon:push:branches:-mainjobs:build-and-deploy:runs-on:ubuntu-lateststeps:-name:Checkout sourceuses:actions/checkoutv4with:ref:main-name:Setup Node.jsuses:actions/setup-nodev4with:node-version:20-name:Install dependenciesrun:npm install-name:Build siterun:|npx hexo clean npx hexo generate-name:Deploy to GitHub Pagesuses:peaceiris/actions-gh-pagesv3with:github_token:${{secrets.GITHUB_TOKEN}}publish_dir:./public13.2 配置 GitHub Pages仓库 Settings → Pages → Source 选择gh-pages分支。13.3 推送即部署gitadd.gitcommit-mchore: add CI/CDgitpush origin main后续每次 push 到 main 分支GitHub Actions 会自动构建并发布。十四、备份与维护14.1 源码版本控制public/与node_modules/不应纳入版本控制。根目录.gitignore内容.DS_Store Thumbs.db db.json *.log node_modules/ public/ .deploy*/ .deploy_git/ .idea/ .vscode/14.2 推送源码到 GitHubgitinitgitremoteaddorigin gitgithub.com:用户/hexo-source.gitgitadd.gitcommit-minit: hexo btt blog sourcegitbranch-Mmaingitpush-uorigin main14.3 多设备同步新设备拉取源码后gitclone gitgithub.com:用户/hexo-source.git Hexo_btt_webcdHexo_btt_webnpminstall注意node_modules/不入库每次 clone 后必须重新npm install。14.4 数据库备份如有评论系统如使用 Valine、Waline、Disqus 等定期备份对应后端数据库LeanCloud、MongoDB 等。14.5 升级 Hexo 与主题# 升级 hexo 主程序npminstallhexolatest--save# 升级主题npm 方式npmupdate hexo-theme-butterfly# 升级后务必清理重新生成hexo cleanhexo g升级前请先git commit保留备份出问题可快速回滚。十五、常见问题排查15.1hexo server端口被占用# 查看占用 4000 端口的进程lsof-i:4000# macOS/Linuxnetstat-ano|findstr :4000# Windows# 改用其他端口hexo server-p500015.2 部署后页面 404检查public/是否生成了index.html检查服务器网站根目录路径是否正确检查 Nginxroot配置与实际目录是否一致15.3 样式丢失 / 资源 404检查_config.yml中url是否正确若部署在子路径如example.com/blog需配置url:https://example.com/blogroot:/blog/15.4 中文链接乱码在_config.yml设置permalink: :title.html或使用拼音插件安装hexo-abbrlink生成永久短链npminstallhexo-abbrlink--savepermalink:posts/:abbrlink.htmlabbrlink:alg:crc32rep:hex15.5 Git 部署报错Deployer not found: git未安装部署插件执行npminstallhexo-deployer-git--save15.6 文章不显示文件必须放在source/_posts/下Front-matter 必须以---包裹且格式正确草稿默认不发布需hexo publish或执行hexo server --draft预览15.7 主题配置不生效检查_config.yml中theme字段与themes/目录名一致优先使用_config.theme.yml覆盖配置清理缓存hexo clean附录常用命令速查表命令作用hexo init folder初始化博客hexo new title新建文章hexo new page name新建页面hexo new draft title新建草稿hexo publish title发布草稿hexo server/hexo s本地预览hexo generate/hexo g生成静态文件hexo deploy/hexo d部署到远端hexo clean清理缓存hexo list post列出文章hexo version/hexo -v查看版本hexo g -d生成并部署hexo s --debug调试模式预览部署流程总览环境准备 (Node.js Git Hexo CLI) ↓ 本地初始化 (hexo init → npm install) ↓ 站点配置 (_config.yml) ↓ 主题安装与配置 (theme _config.theme.yml) ↓ 写作 (hexo new → 编辑 Markdown) ↓ 本地预览 (hexo s) ↓ 生成静态文件 (hexo clean hexo g) ↓ 选择部署方案 (GitHub Pages / VPS / 宝塔 / Vercel) ↓ 域名绑定 HTTPS ↓ CI/CD 自动化 (可选) ↓ 持续写作与维护 文档创建日期2026-08-14 项目Hexo_butt_web✍️ 维护者请根据实际情况补充如部署过程中遇到未涵盖的问题可参考Hexo 官方文档https://hexo.io/zh-cn/docs/Hexo GitHub Issueshttps://github.com/hexojs/hexo/issues