当前位置：首页 > news >正文

基于Github Pages搭建个人博客站点：hexo环境搭建、本地预览与发布

news 2025/8/7 13:43:29

步骤

确认 Hexo 博客的源文件在哪里
安装 Hexo 命令行工具：npm install -g hexo-cli

在源文件目录中使用 hexo new "文章标题" 创建新文章
编辑生成的 Markdown 文件

使用 hexo generate 生成静态文件
使用 hexo deploy 部署到这个 GitHub Pages 仓库

设置Hexo博客环境

首先我们需要确保你的系统已经安装了 Node.jshttps://learn.microsoft.com/zh-cn/windows/dev-environment/javascript/nodejs-on-windows，在windows上通过nvm-windows安装Node.js和npm

节点版本管理器（通常称为 nvm）是安装多个版本的 Node.js的最常用方法，但仅适用于 Mac/Linux，在 Windows 上不受支持。相反，我们建议安装 nvm-windows，然后使用它安装 Node.js 和节点包管理器（npm）。

Power shell中执行npm --version失败，可以参考

https://learn.microsoft.com/zh-cn/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.5#powershell-execution-policies

PowerShell 执行策略并说明如何管理它们

检查 Node.js 环境：

PS C:\WINDOWS\system32> node -v
v22.18.0
PS C:\WINDOWS\system32> npm -v
10.9.3

安装 Hexo 命令行工具并创建一个新的博客源文件目录：

npm install -g hexo-cli

创建一个新的 Hexo 博客源文件目录。我们将其命名为 blog-source

hexo init blog-source 
cd blog-source 
npm install

第一步若出现可以改用 git clone git@github.com:hexojs/hexo-starter.git 先克隆好

git clone https://github.com/hexojs/hexo-starter.git/
Cloning into ‘hexo-starter’…
fatal: unable to access ‘https://github.com/hexojs/hexo-starter.git/’: OpenSSL SSL_read: Connection was reset, errno 10054

安装一些必要的插件，特别是 Git 部署插件：

npm install hexo-deployer-git --save

配置博客，改配置文件来设置你的博客信息：

# Hexo Configuration
## Basics
title: Programming In Bug
subtitle: '编程之路'
description: '分享编程经验与心得'
keywords:
author: EndlessGo
language: zh-CN
timezone: 'Asia/Shanghai'# URL
## Set your site url here
url: https://endlessgo.github.io
root: /
permalink: :year/:month/:day/:title/
permalink_defaults:
pretty_urls:trailing_index: truetrailing_html: true# Directory
source_dir: source
public_dir: public
tag_dir: tags
archive_dir: archives
category_dir: categories
code_dir: downloads/code
i18n_dir: :lang
skip_render:# Writing
new_post_name: :title.md
default_layout: post
titlecase: false
external_link:enable: truefield: siteexclude: ''
filename_case: 0
render_drafts: false
post_asset_folder: true
relative_link: false
future: true
highlight:enable: trueline_number: trueauto_detect: falsetab_replace: ''wrap: truehljs: false
prismjs:enable: falsepreprocess: trueline_number: truetab_replace: ''# Category & Tag
default_category: uncategorized
category_map:
tag_map:# Metadata elements
meta_generator: true# Date / Time format
date_format: YYYY-MM-DD
time_format: HH:mm:ss# Pagination
per_page: 10
pagination_dir: page# Include / Exclude file(s)
include:
exclude:
ignore:# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
theme: landscape# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:type: gitrepo: https://github.com/EndlessGo/EndlessGo.github.io.gitbranch: main

在vscode terminal中运行npm和nvm等指令

若无法运行，可以尝试让 VS Code 的终端继承 PATH，步骤如下

在 VS Code 里打开设置

搜索 terminal.integrated.env.windows

在settings.json 中加入

    "terminal.integrated.env.windows": {"PATH": "D:\\exe\\nodejs\\;D:\\exe\\nvm\\;${env:PATH}"}

编写markdown文章测试与本地预览

让我们创建一个测试文章来确保一切正常工作，会在source/_posts/目录下创建文件my-first-test-blog.md

hexo new "my first test blog"

编辑文章

---
title: 我的第一篇博客
date: 2024-02-06 14:55:30
tags: 
- 博客
- Hexo
categories:
- 技术笔记
---## 欢迎来到我的博客这是我使用 Hexo 搭建的个人博客的第一篇文章。在这里，我将会分享:- 编程技术心得
- 学习笔记
- 项目经验
- 个人感悟### Markdown 示例这是一个 Markdown 语法的简单示例：```python
def hello_world():print("Welcome to my blog!")
```#### 列表示例
1. 第一项
2. 第二项
3. 第三项#### 引用示例
> 学习编程最好的方式就是动手实践### 结语希望这个博客能够记录我的成长历程，也希望能帮助到其他人！

本地预览：在blog-source目录下执行，生成静态文件并启动本地服务器来预览

hexo clean && hexo generate && hexo server

若出现报错

ERROR Cannot find module 'hexo' from 'D:\code\git\EndlessGo.github.io'
ERROR Local hexo loading failed in D:\code\git\EndlessGo.github.io
ERROR Try running: 'rm -rf node_modules && npm install --force'windwos下直接执行
npm install --force
npm audit fix

服务器已经启动，你可以通过访问 http://localhost:4000 来预览你的博客

D:\blog\blog-source>hexo clean && hexo generate && hexo server
INFO  Validating config
INFO  Validating config
INFO  Start processing
INFO  Files loaded in 98 ms
INFO  Generated: archives/2024/index.html
INFO  Generated: archives/index.html
INFO  Generated: archives/2025/index.html
INFO  Generated: archives/2024/02/index.html
INFO  Generated: archives/2025/08/index.html
INFO  Generated: tags/Hexo/index.html
INFO  Generated: index.html
INFO  Generated: tags/博客/index.html
INFO  Generated: categories/技术笔记/index.html
INFO  Generated: css/style.css
INFO  Generated: fancybox/jquery.fancybox.min.css
INFO  Generated: js/script.js
INFO  Generated: fancybox/jquery.fancybox.min.js
INFO  Generated: js/jquery-3.6.4.min.js
INFO  Generated: css/images/banner.jpg
INFO  Generated: 2025/08/05/hello-world/index.html
INFO  Generated: 2024/02/06/my-first-test-blog/index.html
INFO  17 files generated in 214 ms
INFO  Validating config
INFO  Start processing
INFO  Hexo is running at http://localhost:4000/ . Press Ctrl+C to stop.

发布GitHub

当你要发布文章时，使用以下命令：

文章格式：
- 每篇文章开头都有 Front-matter 配置（就是 --- 之间的内容）
- 可以设置标签（tags）和分类（categories）
- 支持所有 Markdown 语法
图片支持：
- post_asset_folder: true，这意味着每次创建新文章时，会自动创建同名文件夹
- 可以将图片放在这个文件夹中，然后在文章中使用相对路径引用

总结

写作新文章：
1. 使用命令 hexo new "文章标题" 创建新文章，位于 source/_posts 目录下对应的.md文件
2. 使用任何支持 Markdown 的编辑器编辑文章
本地预览
1. hexo clean && hexo generate && hexo server
2. 访问 http://localhost:4000 来预览你的博客
发布github
1. hexo clean && hexo generate && hexo deploy