1. 为什么选择Docusaurus搭建个人网站

作为一名技术博主，我尝试过各种静态网站生成工具，最终选择Docusaurus作为我的主力平台。这个由Facebook开源的静态网站生成器特别适合技术文档和个人知识库的构建。它基于React开发，内置Markdown支持，同时具备完善的插件生态系统。

Docusaurus的核心优势在于：

• 极简的配置流程：通过npx create-docusaurus@latest命令即可快速初始化项目
• 响应式设计：自动适配各种终端设备
• 强大的文档功能：支持版本控制、全文搜索等专业特性
• 丰富的主题定制：可以通过Swizzle机制灵活修改组件

2. 本地环境准备与安装

2.1 系统要求检查

在开始之前，请确保你的开发环境满足以下要求：

• Node.js v16.14或更高版本
• npm或yarn包管理器
• Git版本控制系统（可选但推荐）

可以通过以下命令验证环境：

node -v npm -v git --version

2.2 项目初始化步骤

1. 打开终端，进入你希望创建项目的目录
2. 执行初始化命令：

npx create-docusaurus@latest my-website classic

3. 选择项目模板（推荐classic模板）
4. 等待依赖安装完成

提示：如果网络环境不佳，可以使用淘宝镜像加速安装：

npm config set registry https://registry.npmmirror.com

3. 项目结构与配置详解

3.1 核心目录结构

初始化完成后，项目目录结构如下：

my-website/ ├── blog/ # 博客文章 ├── docs/ # 文档内容 ├── src/ # 自定义组件 ├── static/ # 静态资源 ├── docusaurus.config.js # 主配置文件 └── package.json # 项目依赖

3.2 关键配置文件解析

docusaurus.config.js是项目的核心配置文件，主要包含：

module.exports = { title: '我的网站', // 网站标题 tagline: 'Dinosaurs are cool', // 副标题 url: 'https://your-site.com', // 网站URL baseUrl: '/', // 基础路径 projectName: 'my-website', // 项目名称 // 更多配置项... }

4. 本地开发与内容创作

4.1 启动开发服务器

执行以下命令启动本地开发环境：

npm run start

这将启动一个热重载的开发服务器，通常运行在http://localhost:3000

4.2 添加新内容

1. 创建新文档：

   • 在docs目录下新建Markdown文件
   • 在文件头部添加元信息（front matter）：

   --- id: my-doc title: 我的文档 ---

2. 撰写博客文章：

   • 在blog目录下新建Markdown文件
   • 文件名格式：YYYY-MM-DD-my-blog-post.md

5. 构建生产版本

当内容准备就绪后，需要构建生产版本：

npm run build

构建产物将输出到build目录，包含优化后的静态文件。

6. 实现外部访问方案

6.1 内网穿透工具选择

要让本地运行的网站能够被外部访问，可以考虑以下方案：

1. 云服务器反向代理
2. 内网穿透工具（如frp、ngrok）
3. 端口映射

6.2 使用frp实现内网穿透

1. 准备一台具有公网IP的服务器
2. 在服务器端安装frps（服务端）
3. 在本地安装frpc（客户端）
4. 配置frpc.ini：

[common] server_addr = your-server-ip server_port = 7000 [web] type = tcp local_ip = 127.0.0.1 local_port = 3000 remote_port = 6000

7. 部署到生产环境

7.1 静态托管平台选择

推荐几种免费的静态网站托管服务：

• GitHub Pages
• Vercel
• Netlify
• Cloudflare Pages

7.2 GitHub Pages部署流程

1. 在GitHub创建新仓库
2. 将本地项目推送到仓库
3. 配置GitHub Actions自动化部署
4. 在仓库Settings中启用GitHub Pages

8. 常见问题与解决方案

8.1 构建失败排查

常见构建错误及解决方法：

1. 内存不足：增加Node.js内存限制

export NODE_OPTIONS="--max-old-space-size=4096"

2. 依赖冲突：删除node_modules后重新安装
3. 配置错误：检查docusaurus.config.js语法

8.2 样式不生效问题

如果自定义样式未生效：

1. 确保样式文件放在static/css目录
2. 检查是否正确引入了CSS文件
3. 清除浏览器缓存后重试

9. 进阶优化技巧

9.1 性能优化建议

1. 启用gzip压缩
2. 使用CDN加速静态资源
3. 优化图片大小
4. 延迟加载非关键资源

9.2 SEO优化配置

在docusaurus.config.js中添加：

module.exports = { // ... themeConfig: { metadata: [ {name: 'keywords', content: '技术,博客,文档'}, {name: 'description', content: '我的个人技术博客'} ], } }

经过实际使用，我发现Docusaurus的版本控制功能特别实用。当文档需要重大更新时，可以创建新版本而保留旧版内容，这对技术文档的维护非常有帮助。另外，通过合理配置algolia可以实现高效的全文搜索，大幅提升用户体验。