DoraCMS开发文档

主题

环境准备 ​

本文档将指导你准备 DoraCMS 开发和运行所需的环境。

系统要求 ​

操作系统 ​

支持以下操作系统：

  • macOS 10.14+
  • Linux (Ubuntu 18.04+, CentOS 7+, Debian 9+)
  • Windows 10/11 (推荐使用 WSL2)

硬件要求 ​

环境CPU内存硬盘
开发2 核+4GB+10GB+
生产4 核+8GB+50GB+

必需软件 ​

1. Node.js ​

版本要求： Node.js 16.x 或更高版本

安装方法：

bash
# 使用 Homebrew
brew install node@18

# 验证安装
node -v  # 应显示 v18.x.x
npm -v
bash
# 使用 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node -v
npm -v
bash
# 下载并安装 Node.js
# https://nodejs.org/

# 验证安装
node -v
npm -v

推荐使用 nvm 管理 Node.js 版本：

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

# 安装 Node.js
nvm install 18
nvm use 18
nvm alias default 18

2. 包管理器 (pnpm) ​

DoraCMS 使用 pnpm 作为包管理器，相比 npm 和 yarn 更快、更节省磁盘空间。

安装 pnpm：

bash
# 通过 npm 安装
npm install -g pnpm

# 验证安装
pnpm -v

3. 数据库 ​

选择以下数据库之一：

MongoDB (推荐) ​

版本要求： MongoDB 4.4+

bash
# 使用 Homebrew
brew tap mongodb/brew
brew install mongodb-community@7.0

# 启动 MongoDB
brew services start mongodb-community@7.0

# 验证安装
mongosh --version
bash
# Ubuntu/Debian
wget -qO - https://www.mongodb.org/static/pgp/server-7.0.asc | sudo apt-key add -
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list
sudo apt-get update
sudo apt-get install -y mongodb-org

# 启动 MongoDB
sudo systemctl start mongod
sudo systemctl enable mongod

# 验证安装
mongosh --version
bash
# 使用 Docker 快速启动
docker run -d \
  --name mongodb \
  -p 27017:27017 \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=admin123 \
  mongo:7.0

MariaDB (可选) ​

版本要求： MariaDB 10.5+

bash
brew install mariadb
brew services start mariadb
bash
sudo apt-get install mariadb-server
sudo systemctl start mariadb
sudo systemctl enable mariadb
bash
docker run -d \
  --name mariadb \
  -p 3306:3306 \
  -e MYSQL_ROOT_PASSWORD=123456 \
  mariadb:10.11

4. Redis (可选，推荐生产环境) ​

版本要求： Redis 6.0+

bash
brew install redis
brew services start redis
bash
sudo apt-get install redis-server
sudo systemctl start redis
sudo systemctl enable redis
bash
docker run -d \
  --name redis \
  -p 6379:6379 \
  redis:7-alpine

快速验证 ​

安装完成后，运行以下命令验证环境：

bash
# 1. 检查 Node.js
node -v    # 应显示 v16.x.x 或更高

# 2. 检查 pnpm
pnpm -v    # 应显示版本号

# 3. 检查 MongoDB (如果使用)
mongosh --eval "db.version()"  # 应显示 MongoDB 版本

# 4. 检查 Redis (如果使用)
redis-cli ping  # 应返回 PONG

使用 Docker 快速启动 ​

如果你熟悉 Docker，可以使用 Docker Compose 一键启动所有依赖：

1. 创建 docker-compose.yml：

yaml
version: '3.8'
services:
  mongodb:
    image: mongo:7.0
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: admin123
    volumes:
      - mongodb_data:/data/db

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  mongodb_data:

2. 启动服务：

bash
docker-compose up -d

开发工具推荐 ​

代码编辑器 ​

  • VS Code (推荐) - 配合以下插件：
    • ESLint
    • Prettier
    • Vue Language Features (Volar)
    • MongoDB for VS Code

数据库管理工具 ​

  • MongoDB：

    • MongoDB Compass (官方 GUI)
    • Studio 3T

  • MariaDB/MySQL：

    • DBeaver
    • MySQL Workbench
    • TablePlus

API 测试工具 ​

  • Postman 或 Insomnia
  • REST Client (VS Code 插件)

常见问题 ​

1. Node.js 版本过低 ​

问题： 运行项目时提示 Node.js 版本不兼容

解决：

bash
# 使用 nvm 切换版本
nvm install 18
nvm use 18

2. pnpm 命令未找到 ​

问题： 安装 pnpm 后命令不可用

解决：

bash
# 重新安装 pnpm
npm install -g pnpm

# 如果使用 nvm，可能需要重新安装
nvm use 18
npm install -g pnpm

3. MongoDB 连接失败 ​

问题： 无法连接到 MongoDB

解决：

bash
# 检查 MongoDB 是否运行
# macOS
brew services list | grep mongodb

# Linux
sudo systemctl status mongod

# 查看日志
# macOS
tail -f /usr/local/var/log/mongodb/mongo.log

# Linux
sudo tail -f /var/log/mongodb/mongod.log

4. 端口被占用 ​

问题： 启动服务时提示端口已被占用

解决：

bash
# 查找占用端口的进程
# macOS/Linux
lsof -i :8080
lsof -i :27017

# Windows
netstat -ano | findstr :8080

# 杀死进程
kill -9 <PID>

下一步 ​

环境准备完成后，你可以：

  1. 📖 快速开始 - 启动你的第一个 DoraCMS 项目
  2. ⚙️ 环境配置 - 配置开发环境
  3. 🗄️ 数据库配置 - 配置数据库连接

小结 ​

✅ Node.js 18+ - JavaScript 运行环境
✅ pnpm - 包管理器
✅ MongoDB/MariaDB - 数据库（二选一）
✅ Redis (可选) - 缓存服务
✅ 开发工具 - 代码编辑器和管理工具

环境准备完成后，即可开始 DoraCMS 的开发之旅！🚀