云信AI部署

Azure VM平台搭建Docusaurus开发环境的完整教程

云信安装大师
90
AI 质量分
10 5 月, 2025
2 分钟阅读
0 阅读

Azure VM平台搭建Docusaurus开发环境的完整教程

引言

Docusaurus是Meta(原Facebook)开源的一款静态网站生成器，特别适合构建文档网站。本教程将指导你如何在Azure虚拟机上搭建完整的Docusaurus开发环境，让你能够快速开始文档网站的开发和部署。

准备工作

在开始之前，你需要：

  1. 一个有效的Azure账号
  2. 基本的Linux命令行知识
  3. 本地SSH客户端(如Windows的PuTTY或Mac/Linux的终端)

第一步：创建Azure虚拟机

1.1 登录Azure门户

访问 Azure门户 并使用你的账号登录。

1.2 创建虚拟机

  1. 在Azure门户中点击”创建资源”
  2. 搜索并选择”虚拟机”
  3. 点击”创建”

1.3 配置虚拟机参数

以下是一些推荐配置：

  • 订阅：选择你的订阅
  • 资源组：创建新组或使用现有组
  • 虚拟机名称：如docusaurus-dev
  • 区域：选择离你最近的区域
  • 映像：Ubuntu Server 20.04 LTS
  • 大小：Standard B2s (2 vCPU,4 GiB内存)足够开发使用
  • 身份验证类型：SSH公钥(更安全)或密码
  • 用户名：设置管理员用户名(如azureuser)
  • SSH公钥源：生成新密钥对或使用现有密钥

注意：建议使用SSH密钥认证而非密码，安全性更高。如果你选择生成新密钥，Azure会提供下载私钥的选项。

1.4 网络和安全设置

确保以下端口开放：
– SSH (22)
– HTTP (80,可选)
– HTTPS (443,可选)

1.5 部署虚拟机

检查所有配置无误后，点击”查看+创建”，然后点击”创建”。部署过程通常需要几分钟。

第二步：连接到虚拟机

部署完成后，你可以通过SSH连接到虚拟机：

代码片段 
ssh -i <私钥路径> <用户名>@<公共IP地址>

例如：

代码片段 
ssh -i ~/Downloads/docusaurus-dev_key.pem azureuser@20.127.123.45

首次连接时可能会提示确认主机指纹，输入yes继续。

第三步：安装必要软件

3.1 更新系统包

代码片段 
sudo apt update && sudo apt upgrade -y

这个命令会更新包列表并升级所有已安装的软件包到最新版本。

3.2 安装Node.js和npm

Docusaurus需要Node.js环境。我们推荐使用nvm(Node Version Manager)来安装Node.js：

代码片段 
# 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

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

# 安装Node.js LTS版本(推荐16.x或18.x)
nvm install --lts

# 验证安装
node -v && npm -v

3.3 (可选)安装Yarn

虽然npm足够使用，但Yarn有时提供更好的性能：

代码片段 
npm install -g yarn

第四步：安装和配置Docusaurus

4.1 创建新的Docusaurus项目

代码片段 
npx create-docusaurus@latest my-website classic

这个命令会：
1. npx从npm下载并运行create-docusaurus包的最新版本
2. my-website是项目目录名，你可以自定义
3. classic指定使用经典模板(包含文档和博客功能)

注意：如果你想要更简单的初始设置，可以使用basic模板替代classic

4.4 (可选)启用TypeScript支持

如果你想使用TypeScript:

代码片段 
cd my-website && npx @docusaurus/init@latest init --typescript .

第五步：运行开发服务器

进入项目目录并启动开发服务器：

代码片段 
cd my-website && npm run start

这将启动一个本地开发服务器，通常监听在3000端口。由于我们在虚拟机上运行，需要通过SSH隧道访问：

在你的本地机器上运行：

代码片段 
ssh -i <私钥路径> -L3000:localhost:3000 <用户名>@<公共IP地址>

然后你可以在本地浏览器访问 http://localhost:3000/

第六步：(可选)配置生产环境优化

当你准备部署时，可以构建生产优化的版本：

代码片段 
npm run build

构建结果会输出到build目录。你可以使用任何静态文件服务器来托管这些文件。

第七步：(高级)设置持续集成(CI)

如果你想自动化部署流程，可以设置GitHub Actions或其他CI工具。以下是基本的GitHub Actions配置示例：

在.github/workflows/deploy.yml中添加：

代码片段 
name: Deploy to Azure VM

on:
 push:
   branches: [ main ]

jobs:
 deploy:
   runs-on: ubuntu-latest

   steps:
   - uses: actions/checkout@v2

   - name: Set up Node.js 
     uses: actions/setup-node@v2 
     with:
       node-version: '16'

   - name: Install dependencies 
     run: npm install

   - name: Build website 
     run: npm run build

   - name: Deploy to Azure VM 
     uses: appleboy/scp-action@master 
     with:
       host: ${{ secrets.AZURE_VM_HOST }}
       username: ${{ secrets.AZURE_VM_USERNAME }}
       key: ${{ secrets.AZURE_VM_SSH_KEY }}
       source: "build/"
       target: "/var/www/docusaurus"

记得在GitHub仓库的Settings > Secrets中配置相应的机密信息。

常见问题解决

SSH连接问题

如果无法连接：
1. 超时：检查网络安全组规则是否允许SSH(端口22)
2.认证失败：
-确认用户名正确
-对于密钥认证,确保使用了正确的私钥文件
-检查私钥文件权限(应设置为600)

Node.js版本问题

如果遇到兼容性问题：
1.Docusaurus v2需要Node.js14或更高版本
2.Docusaurus v3需要Node.js16或更高版本
3.nvm ls查看已安装版本,nvm use切换版本

端口冲突

如果3000端口被占用：
1.npm run start — –port=4000指定其他端口
2.lsof-i :3000查看占用进程,kill终止进程

总结

通过本教程,你已经完成了以下工作：
✅在Azure上创建了Ubuntu虚拟机
✅通过SSH安全连接到虚拟机
✅安装了Node.js和npm/yarn
✅初始化了Docusaurus项目
✅启动了开发服务器并通过隧道访问

现在你可以开始定制你的文档网站了！Docusaurus提供了丰富的主题和插件系统,你可以参考官方文档进一步探索其功能。

原创 高质量