GitHub热门项目Docusaurus：在Azure VM环境下的安装与使用

引言

Docusaurus是Meta（原Facebook）开源的一款现代化的静态网站生成器，专门为文档网站设计。它支持Markdown编写内容、内置搜索功能、版本控制等特性，非常适合技术文档的构建。本文将详细介绍如何在Azure VM环境下安装和使用Docusaurus。

准备工作

在开始之前，请确保您已经完成以下准备：

一个可用的Azure账号
已创建一台运行Ubuntu 20.04 LTS或更高版本的Azure VM
SSH访问权限（推荐使用SSH密钥认证）
基本的Linux命令行知识

注意：本文假设您已经创建了一个至少具有2个vCPU和4GB内存的Azure VM（B2s或更高配置）。

步骤一：连接到Azure VM

首先，使用SSH连接到您的Azure VM：

代码片段

ssh -i ~/.ssh/your_private_key.pem username@your-vm-public-ip

参数说明：
– -i：指定SSH私钥文件路径
– username：您在创建VM时设置的用户名（通常是azureuser）
– your-vm-public-ip：VM的公网IP地址

步骤二：安装必要的依赖项

Docusaurus需要Node.js环境。我们将使用nvm（Node Version Manager）来安装Node.js：

代码片段

# 更新系统包列表
sudo apt update && sudo apt upgrade -y

# 安装curl和git（如果尚未安装）
sudo apt install -y curl git

# 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

# 使nvm在当前shell中可用
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 验证nvm安装
nvm --version

# 安装Node.js LTS版本（Docusaurus推荐版本）
nvm install --lts

# 验证Node.js和npm安装
node --version
npm --version

实践经验：
– 使用nvm而不是直接apt安装Node.js，可以方便地切换不同版本
– Docusaurus需要Node.js v16.14或更高版本，但低于v17

步骤三：创建Docusaurus项目

现在我们可以创建一个新的Docusaurus项目：

代码片段

# 创建一个新目录并进入
mkdir my-docusaurus-site && cd my-docusaurus-site

# 使用npm初始化Docusaurus项目
npm init docusaurus@latest . classic

# 或者使用yarn（如果更喜欢）
# yarn create docusaurus . classic

这个命令会交互式地询问一些配置选项：

代码片段

√ Which language do you want to use? » TypeScript
√ Do you want to use a template? » classic
√ What should we name this site? ... my-docusaurus-site

注意事项：
– “classic”模板是最常用的启动模板，包含文档和博客功能
– TypeScript是可选的，但推荐用于更好的类型安全

步骤四：运行开发服务器

让我们启动开发服务器查看效果：

代码片段

npm run start

这将启动一个本地开发服务器，通常运行在http://localhost:3000。但由于我们在Azure VM上，需要通过SSH隧道访问：

代码片段

# 在本地机器上执行（不是VM中）
ssh -i ~/.ssh/your_private_key.pem -L 3000:localhost:3000 username@your-vm-public-ip

然后在本地浏览器访问http://localhost:3000即可看到Docusaurus默认页面。

步骤五：基本配置修改

让我们修改一些基本配置。编辑docusaurus.config.js文件：

“`javascript title=”docusaurus.config.js”
module.exports = {
title: ‘我的技术文档’, // 网站标题
tagline: ‘记录与分享’, // slogan副标题

};

代码片段


还可以修改导航栏配置：

```javascript title="docusaurus.config.js"
module.exports = {

};

保存后，开发服务器会自动重新加载页面。

步骤六：添加新文档页面

在Docusaurus中添加新文档非常简单：

Markdown文件放在docs目录下，例如创建docs/getting-started.md
sidebars.js中配置导航菜单结构：

“`javascript title=”sidebars.js”
module.exports = {

};

代码片段


3. Docusaurus会自动根据文件目录结构生成对应的URL路径。

## Azure VM上的生产部署建议

对于生产环境部署，我们建议:

1. **构建静态文件**:

npm run build

这会生成静态文件到build目录。

使用Nginx作为Web服务器:

代码片段

sudo apt install -y nginx
sudo cp -r build/* /var/www/html/
sudo systemctl restart nginx

设置防火墙规则:

确保Azure网络安全组允许HTTP(80)和HTTPS(443)流量。

启用HTTPS:

考虑使用Let’s Encrypt免费证书:

代码片段

sudo apt install certbot python3-certbot-nginx -y 
sudo certbot --nginx -d your-domain.com

设置自动更新证书:

代码片段

sudo crontab -e

添加以下行:

代码片段

0 */12 * * * /usr/bin/certbot renew --quiet

CI/CD自动化部署 (可选)

您可以设置GitHub Actions来自动构建和部署到Azure VM:

在VM上设置部署用户:

代码片段

sudo adduser deployer 
sudo usermod -aG www-data deployer 
sudo chown -R deployer:www-data /var/www/html 
sudo chmod -R g+rwX /var/www/html

创建GitHub Actions工作流文件 .github/workflows/deploy.yml:

代码片段

name: Deploy to Azure VM 

on:


jobs:

      # ...其他步骤...
      # SSH连接并部署

在GitHub仓库设置中添加SSH私钥作为secret

常见问题解决

端口无法访问问题

代码片段

# Azure门户检查网络安全组规则是否允许端口3000/80/443入站流量

# Linux防火墙检查 (Ubuntu通常使用ufw)
sudo ufw allow http 
sudo ufw allow https

# Nginx服务状态检查  
sudo systemctl status nginx

内存不足错误
如果构建过程中出现内存不足错误:

代码片段

# Node.js内存限制调整 (临时方案)
export NODE_OPTIONS=--max-old-space-size=4096

# Azure VM升级到更高内存规格 (长期方案)

依赖项冲突
如果遇到依赖项问题:

代码片段

rm -rf node_modules package-lock.json

npm cache clean --force

npm install  

npm dedupe

自定义域名设置
要在DNS提供商处添加A记录指向VM公网IP:
性能优化建议
对于高流量站点:
备份策略
定期备份重要数据:
监控与日志
设置基本监控:

Docusaurus高级功能探索 (可选)

10.

Docker容器化部署 (可选)

对于更一致的部署环境,可以考虑使用Docker:

Kubernetes集群部署 (高级)

如果您有Kubernetes集群,可以这样部署:

通过以上步骤,您应该已经在Azure VM上成功搭建了Docusaurus文档站点。这个轻量级但功能强大的工具可以帮助您快速建立专业的技术文档网站。随着内容的增加,您可以进一步探索其插件系统和自定义主题功能,打造更符合品牌形象的文档平台。

关键点回顾:
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.

下一步学习方向建议:
– 官方文档
– 社区插件
– 主题定制指南