1. 为什么选择 Docusaurus GitHub Pages如果你和我一样是个喜欢写点东西、记录学习过程的技术人可能早就动过自己搭博客的念头。但一搜教程满眼的 WordPress、Hexo、Hugo还有各种要自己配置服务器、买域名、搞备案的复杂流程瞬间就头大了。我也被劝退过好几次直到一个朋友轻描淡写地说“试试 Docusaurus 吧用 GitHub Pages 托管完全免费而且巨简单。”我抱着怀疑的态度试了试结果从零开始到博客上线只花了一个下午。那种“原来这么容易”的惊喜感让我立刻决定把整个过程写下来。Docusaurus是 Meta原 Facebook开源的一个静态站点生成器专门为文档和博客设计背靠 React 生态颜值和功能都在线。GitHub Pages是 GitHub 提供的免费静态网站托管服务你只需要把代码推上去它就能自动帮你生成一个可通过互联网访问的网站。这两者结合简直是“天作之合”。你不需要懂服务器运维不需要买虚拟主机甚至不需要信用卡。整个过程就像在本地写 Markdown 笔记然后用几条命令“发布”到网上一样自然。对于学生、技术新人、或者只是想有个地方安放自己技术思考的朋友来说这是目前我见过最友好、最省心的方案。它把搭建个人技术博客的门槛从“专业运维”拉低到了“会用电脑”的水平。2. 准备工作安装必备的“工具包”工欲善其事必先利其器。在开始敲代码之前我们需要在电脑上安装几个必要的软件。别担心它们都是免费的而且安装过程就像安装 QQ 一样简单。我会把每一步都拆开讲清楚确保你跟着做不会卡住。2.1 安装 Node.js 和包管理器Node.js是运行 Docusaurus 的“发动机”我们必须先安装它。打开 Node.js 官网你会看到两个版本LTS长期支持版和 Current最新版。请务必选择 LTS 版本它更稳定兼容性更好。下载后直接运行安装程序一路点击“Next”即可。安装完成后我们需要验证一下。打开你的命令行工具Windows 用户按WinR输入cmd后回车Mac 用户打开“终端”输入以下命令并回车node -v npm -v如果分别显示了类似v18.17.0和9.6.7的版本号恭喜你安装成功了这里的npm是随 Node.js 一起安装的包管理工具我们可以用它来安装其他软件。不过社区更推荐使用yarn速度更快一些。我们可以用 npm 来安装 yarnnpm install -g yarn安装完成后同样用yarn --version检查一下。为了后续安装包的速度更快我建议给 yarn 配置一下国内的镜像源这能极大提升下载速度避免超时。在命令行中依次执行yarn config set registry https://registry.npmmirror.com -g yarn config set sass_binary_site https://npmmirror.com/mirrors/node-sass -g2.2 安装 Git 和代码编辑器Git是一个版本控制系统我们用它来管理博客的代码并推送到 GitHub。去 Git 官网 下载安装即可安装过程中所有选项保持默认就行。安装后在命令行输入git --version验证。接下来需要一个顺手的代码编辑器来写博客和配置文件。我强烈推荐Visual Studio Code (VSCode)它免费、强大、插件生态丰富对前端和 Markdown 的支持特别好。从 VSCode 官网 下载安装。安装后我建议做一个小设置右键点击 VSCode 图标选择“以管理员身份运行”仅 Windows 系统可能需要这可以避免后续一些因权限导致的奇怪报错。2.3 注册 GitHub 账号这是最后一步准备。访问 GitHub 官网用你的邮箱注册一个账号。用户名Username想好一点因为它会直接成为你博客域名的一部分比如你的用户名.github.io。注册过程很简单就不赘述了。至此我们的“工具包”就全部齐备了。3. 创建你的第一个 Docusaurus 网站工具准备好了现在让我们开始“造房子”。Docusaurus 提供了一条超级简单的命令能一键生成一个包含基础布局、导航栏和页脚的网站骨架。3.1 一键初始化项目打开命令行找一个你喜欢的目录比如D:\Projects或~/Documents执行下面的命令npx create-docusauruslatest my-blog classic我来解释一下这条命令npx一个工具可以让你直接运行 npm 包里的命令而无需先全局安装这个包。create-docusauruslatest表示使用最新版的 Docusaurus 创建工具。my-blog这是你项目的文件夹名称你可以改成任何你喜欢的名字比如tech-notes,personal-site。classic这是初始模板的主题我们选择经典的即可它包含了博客和文档功能。命令运行后它会自动下载所需的文件这个过程可能需要一两分钟取决于你的网络。完成后进入项目目录并启动开发服务器看看效果cd my-blog yarn start # 或者 npm run start几秒钟后你的默认浏览器会自动打开http://localhost:3000。一个干净、现代的技术博客就出现在你眼前了左侧是导航栏中间是欢迎内容。你可以点击页面上的链接随意浏览。这个服务器运行在本地你对代码的任何修改都会实时热更新到页面上体验非常流畅。想停止服务器在命令行按Ctrl C即可。3.2 初探项目结构用 VSCode 打开你的my-blog文件夹可以在项目目录下直接运行code .命令。你会看到类似下面的文件结构my-blog/ ├── blog/ # 博客目录你的文章.md文件放在这里 │ ├── 2019-05-28-first-blog.md │ └── 2021-08-26-welcome.md ├── docs/ # 文档目录如果你写项目文档就放这里 ├── src/ │ ├── components/ # 自定义的 React 组件 │ ├── css/ # 自定义样式 │ └── pages/ # 独立页面如“关于我” ├── static/ # 静态资源如图片、favicon ├── docusaurus.config.js # 网站的核心配置文件 ├── package.json # 项目依赖和脚本定义 └── sidebar.js # 文档侧边栏导航配置现在你不需要理解每一个文件只需要知道你的博客文章就是 Markdown 文件直接扔进blog/文件夹就行。Docusaurus 会自动按日期排序并生成列表页。是不是简单得有点不可思议4. 个性化配置让博客拥有你的印记默认的网站虽然能运行但还带着 Docusaurus 的标识。我们需要把它变成“你的”博客。最关键的一步就是修改docusaurus.config.js这个文件。4.1 修改核心配置文件用 VSCode 打开docusaurus.config.js。它看起来可能有点复杂但我们需要改的只有几处关键信息。找到title,tagline,url,favicon以及 GitHub Pages 相关的配置部分。module.exports { title: 小明的技术笔记, // 网站标题会显示在浏览器标签和导航栏 tagline: 记录与分享每天进步一点点, // 网站副标题或标语 url: https://YourUserName.github.io, // 你的 GitHub Pages 网址 baseUrl: /, // 如果你的网站不在根目录这里需要修改我们保持 / favicon: img/favicon.ico, // 网站图标可以将你的 logo 图片放到 static/img/ 下并修改这里 // GitHub pages 部署配置非常重要 organizationName: YourUserName, // 你的 GitHub 用户名 projectName: YourUserName.github.io, // 你的仓库名通常就是 用户名.github.io deploymentBranch: gh-pages, // 部署分支固定为 gh-pages trailingSlash: false, // 是否在链接末尾加斜杠通常保持 false // ... 其他配置暂时可以不用动 };请务必将YourUserName替换成你真实的 GitHub 用户名。比如我的用户名叫xiaoming那么url就填https://xiaoming.github.ioorganizationName和projectName都填xiaoming。4.2 更换首页图片与文案默认首页有一张大的背景图和一些欢迎文案。你可以在src/pages/index.js文件里修改它。这个文件是一个 React 组件但即使你不懂 React也能看懂一些简单的修改。比如找到header className{clsx(hero hero--primary, styles.heroBanner)}这个部分修改其中的title和tagline就能改变首页主标题和副标题。想换背景图去static/img/目录下替换图片然后在src/css/custom.css中修改heroBanner相关的背景样式即可。一开始你可以先简单改改文字感受一下变化。5. 部署到 GitHub Pages让全世界看到你的博客这是最激动人心的一步把我们本地运行的网站发布到公网上让任何人都能访问。得益于 GitHub Pages 和 Docusaurus 的深度集成这个过程只需要一条命令。5.1 在 GitHub 上创建特殊仓库首先我们需要在 GitHub 上创建一个非常特殊的仓库仓库名必须严格遵守格式你的用户名.github.io。比如我的用户名是xiaoming那么仓库名就必须是xiaoming.github.io。登录 GitHub点击右上角号选择New repository。在Repository name输入框里输入你的用户名.github.io。描述Description可选填。选择Public公开。不要勾选Initialize this repository with a README我们用本地已有的项目初始化。点击Create repository创建。创建成功后你会看到一个快速设置页面。先放着不管我们回到命令行。5.2 关联本地项目与远程仓库在你的项目根目录my-blog下依次执行以下 Git 命令将本地代码与刚创建的 GitHub 仓库关联起来# 初始化本地 Git 仓库如果之前没初始化过 git init # 将当前所有文件添加到暂存区 git add . # 提交更改并写一条提交信息 git commit -m 初始提交搭建 Docusaurus 博客框架 # 添加远程仓库地址请将下面的 URL 替换成你自己的仓库地址 git remote add origin https://github.com/YourUserName/YourUserName.github.io.git # 将本地代码推送到远程仓库的 main 分支 git push -u origin main执行git push后会提示你输入 GitHub 的用户名和密码注意密码现在一般使用 Personal Access Token你可以在 GitHub 设置中生成。推送成功后刷新你的 GitHub 仓库页面就能看到代码已经上传了。5.3 一键部署神奇的 yarn deploy现在执行 Docusaurus 提供的“魔法”命令yarn deploy # 或者 npm run deploy这条命令会做以下几件事自动执行yarn build将你的网站Markdown、React 组件等编译成最终的 HTML、CSS、JS 静态文件。自动将这些静态文件推送到你 GitHub 仓库的gh-pages分支。GitHub Pages 服务会监测gh-pages分支的更新并自动将其内容部署为网站。等待命令执行完成通常需要1-2分钟。当你在命令行看到Published之类的成功提示后打开浏览器访问https://你的用户名.github.io。恭喜你的个人技术博客已经正式上线了这种感觉非常奇妙几分钟前它还只存在于你的电脑里现在全世界任何一个有网络的人都能访问它了。6. 撰写与发布你的第一篇博客博客搭好了最重要的当然是写文章。用 Docusaurus 写博客舒服得就像在本地用 Typora 写笔记。6.1 创建新文章在blog目录下新建一个 Markdown 文件。文件名有讲究建议遵循YYYY-MM-DD-文章标题.md的格式例如2023-10-27-hello-docusaurus.md。日期前缀会被 Docusaurus 自动解析为文章的发布时间并用于排序。打开这个新文件在文件最开头需要添加一个“Front Matter”区域用于定义文章的元数据--- slug: hello-docusaurus # 文章在URL中的路径可选不写则用文件名 title: 你好Docusaurus # 文章标题 authors: [小明] # 作者可以是一个列表 tags: [博客, Docusaurus, 教程] # 文章标签 --- 这是我的第一篇用 Docusaurus 发布的博客文章 ## 二级标题 内容... ### 三级标题 更多内容...Front Matter 用---包裹里面是标准的 YAML 格式。写完文章后保存。6.2 本地预览与最终发布在项目根目录下运行yarn start打开本地预览。你会在博客列表页看到你的新文章点击进入查看效果。确认无误后就可以发布到网上了。发布流程和第一次部署一样简单将新增的博客文件提交到 Gitgit add .然后git commit -m 发布新文章你好 Docusaurus将提交推送到 GitHubgit push origin main执行部署命令yarn deploy等待命令完成刷新你的线上博客网站新文章就出现了从此以后你写博客的流程就固定为本地写 Markdown - 提交到 Git - 执行yarn deploy。三步搞定极其优雅。7. 常见问题与避坑指南在实际操作中你可能会遇到一些我当初也踩过的坑。这里我把它们总结出来并提供经过验证的解决方案。7.1 部署命令报错权限或网络问题当你执行yarn deploy或git push时可能会遇到各种超时或拒绝连接的报错。这通常和网络环境有关。错误信息包含443 timeout或Connection refused这通常是网络连接 GitHub 不稳定。可以尝试修改 Git 的全局配置增大缓存区有时能缓解问题git config --global http.postBuffer 524288000错误信息包含OpenSSL SSL_read: Connection was aborted同样可能是网络问题。除了上述方法还可以尝试将 Git 的传输协议从 HTTPS 切换到 SSH但这需要你先配置 SSH Key。一个更简单的临时方案是过一会儿再重试或者切换到一个更稳定的网络环境。7.2 部署时内存溢出 (FATAL ERROR: process out of memory)这是我遇到最棘手的一个问题。在执行yarn deploy构建过程中Node.js 进程可能因为内存不足而崩溃。尤其是在 Windows 系统上或者文章/图片较多时容易发生。解决方案通过设置 Node.js 运行时的最大内存限制来解决。在package.json文件中的scripts部分修改build命令scripts: { build: node --max-old-space-size8192 node_modules/docusaurus/core/bin/docusaurus.js build, // ... 其他脚本 }这里的8192表示分配 8GB 的内存上限你可以根据自己电脑的情况调整为40964GB。修改后再次运行yarn deploy即可。7.3 推送代码冲突non-fast-forward如果你在多个设备上操作了同一个仓库或者 GitHub 仓库的初始状态与本地不同在git push时可能会报non-fast-forward错误。这表示远程仓库有你本地没有的新提交。解决方案先拉取远程的更改并与本地合并再推送。# 拉取远程更新 git pull origin main # 如果拉取时有冲突需要手动解决冲突文件然后再次提交 git add . git commit -m 合并远程更改 # 再次推送 git push origin main7.4 自定义域名可选进阶操作如果你不想用用户名.github.io这个域名可以绑定自己的专属域名比如blog.yourname.com。这需要两个步骤在博客项目的static文件夹下创建一个名为CNAME的文件没有后缀文件内容就是你的一行域名例如blog.yourname.com。去你的域名注册商如阿里云、GoDaddy那里添加两条 DNS 解析记录记录类型A 主机记录 记录值185.199.108.153这是 GitHub Pages 的 IP有多个可以都加上记录类型CNAME 主机记录www 记录值你的用户名.github.io等待 DNS 生效通常几分钟到几小时然后在 GitHub 仓库的Settings - Pages页面可以看到你的自定义域名已经生效了。搭建和部署过程中最需要的就是耐心。遇到报错别慌把错误信息完整地复制到搜索引擎里十有八九能找到答案。技术社区的力量就在于你踩过的坑早就有人填平了并留下了路标。