easygoadmin-wiki/EasyGoAdmin_Iris_Layui/zh/quickstart/environment.md

# 2.1 开发环境准备

:::tip 概述
本章指导您从零搭建开发环境，包括 PHP、Composer、数据库、Node.js 的安装与配置。项目支持 MySQL、PostgreSQL、SQL Server、Oracle、SQLite 五种数据库。
:::

## 安装流程总览

```mermaid
graph TD
    A[开始] --> B[安装 PHP 8.2]
    B --> C[安装 Composer]
    C --> D{选择数据库}
    D --> D1[MySQL]
    D --> D2[PostgreSQL]
    D --> D3[SQLite]
    D --> D4[SQL Server]
    D --> D5[Oracle]
    D1 --> E[安装 Node.js / pnpm]
    D2 --> E
    D3 --> E
    D4 --> E
    D5 --> E
    E --> F[配置开发工具]
    F --> G[环境就绪 ✅]

    style A fill:#e8f5e9
    style G fill:#e8f5e9
    style D fill:#fff3e0
```

## PHP 安装

:::warning 版本要求
项目要求 PHP >= 8.2，推荐使用 8.2.x 稳定版。
:::

### 方式一：XAMPP（推荐新手）

XAMPP 是集成了 Apache + MySQL + PHP 的一键安装包，适合快速搭建开发环境。

::: code-group

```sh [Windows]
# 1. 下载 XAMPP
#    访问 https://www.apachefriends.org/download.html
#    选择 PHP 8.2 版本下载

# 2. 安装完成后，将 PHP 添加到系统 PATH（永久生效）
#    右键「此电脑」→ 属性 → 高级系统设置 → 环境变量
#    在「系统变量」中找到 Path → 编辑 → 新建
#    添加 XAMPP 的 PHP 路径，例如：
#      C:\xampp8.2\php
#    确定保存后，打开新的命令行窗口使生效

# 临时生效（仅当前窗口）：
set PATH=%PATH%;C:\xampp8.2\php

# 3. 验证安装
php -v
# 输出：PHP 8.2.x (cli) ...

# 4. 验证扩展
php -m | findstr "pdo_mysql mbstring gd"
```

```sh [macOS]
# 1. 下载 XAMPP for macOS
#    访问 https://www.apachefriends.org/download.html

# 2. 安装后，将 PHP 添加到 PATH
echo 'export PATH="/Applications/XAMPP/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 3. 验证安装
php -v

# 4. 验证扩展
php -m | grep -E "pdo_mysql|mbstring|gd"
```

:::

### 方式二：包管理器安装

::: code-group

```sh [Ubuntu / Debian]
# 添加 PHP 官方仓库（获取最新版本）
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update

# 安装 PHP 8.2 及常用扩展
sudo apt install -y \
    php8.2 \
    php8.2-fpm \
    php8.2-mysql \
    php8.2-pgsql \
    php8.2-sqlite3 \
    php8.2-mbstring \
    php8.2-xml \
    php8.2-curl \
    php8.2-gd \
    php8.2-zip \
    php8.2-bcmath \
    php8.2-intl \
    php8.2-opcache

# 验证安装
php -v

# 验证扩展
php -m | grep -E "pdo_mysql|pdo_pgsql|pdo_sqlite|mbstring|gd"
```

```sh [Rocky Linux / AlmaLinux]
# 启用 Remi 仓库（提供 PHP 8.2）
sudo dnf install -y epel-release
sudo dnf install -y https://rpms.remirepo.net/enterprise/remi-release-9.rpm

# 启用 PHP 8.2 模块
sudo dnf module reset php -y
sudo dnf module enable php:remi-8.2 -y

# 安装 PHP 及常用扩展
sudo dnf install -y \
    php \
    php-fpm \
    php-mysqlnd \
    php-pgsql \
    php-sqlite3 \
    php-mbstring \
    php-xml \
    php-gd \
    php-zip \
    php-bcmath \
    php-intl \
    php-opcache

# 验证安装
php -v

# 启动 PHP-FPM（Nginx 场景）
sudo systemctl enable php-fpm
sudo systemctl start php-fpm
```

```sh [CentOS / RHEL]
# 启用 Remi 仓库
sudo yum install -y epel-release
sudo yum install -y https://rpms.remirepo.net/enterprise/remi-release-8.rpm

# 启用 PHP 8.2
sudo yum module reset php -y
sudo yum module enable php:remi-8.2 -y

# 安装 PHP 及常用扩展
sudo yum install -y \
    php \
    php-fpm \
    php-mysqlnd \
    php-pgsql \
    php-sqlite3 \
    php-mbstring \
    php-xml \
    php-gd \
    php-zip \
    php-bcmath \
    php-intl \
    php-opcache

# 验证安装
php -v
```

```sh [macOS (Homebrew)]
# 安装 PHP 8.2
brew install php@8.2

# 切换到 8.2 版本
brew link php@8.2 --force

# 验证安装
php -v

# 安装可选扩展（如 gd）
brew install php-gd
```

:::

## PHP 扩展安装

### 必需扩展

| 扩展 | 用途 | 安装命令 |
|------|------|----------|
| `pdo_mysql` | MySQL 数据库驱动 | 已随 php-mysql 安装 |
| `mbstring` | 多字节字符串处理 | 已随 PHP 安装 |
| `json` | JSON 编解码 | PHP 8.2 自带 |
| `openssl` | JWT 签名 / HTTPS | PHP 8.2 自带 |
| `fileinfo` | 文件 MIME 类型检测 | PHP 8.2 自带 |
| `gd` | 图片验证码生成 | 已随 php-gd 安装 |

### 数据库扩展（按需安装）

::: code-group

```sh [MySQL]
# 大多数安装方式已包含
# 如缺失：
sudo apt install php8.2-mysql        # Ubuntu
sudo dnf install php-mysqlnd         # Rocky Linux
```

```sh [PostgreSQL]
sudo apt install php8.2-pgsql        # Ubuntu
sudo dnf install php-pgsql           # Rocky Linux
```

```sh [SQLite]
sudo apt install php8.2-sqlite3      # Ubuntu
sudo dnf install php-sqlite3         # Rocky Linux
```

```sh [SQL Server]
# 安装 Microsoft ODBC Driver
# 参考 https://learn.microsoft.com/sql/connect/odbc/linux-mac/installing-the-microsoft-odbc-driver-for-sql-server

# 安装 PDO_SQLSRV 扩展
sudo pecl install pdo_sqlsrv
echo "extension=pdo_sqlsrv.so" | sudo tee /etc/php/8.2/mods-available/pdo_sqlsrv.ini
sudo phpenmod pdo_sqlsrv
```

```sh [Oracle]
# ThinkPHP 的 Oracle 连接器使用 PDO（pdo_oci 驱动），必须启用 pdo_oci 扩展
#
# Linux：安装 Oracle Instant Client 后，通过 PECL 安装
sudo pecl install pdo_oci
echo "extension=pdo_oci.so" | sudo tee /etc/php/8.2/mods-available/pdo_oci.ini
sudo phpenmod pdo_oci

# Windows / XAMPP：XAMPP 8.2 已自带 php_pdo_oci.dll，只需在 php.ini 中启用
# 编辑 D:\xampp8.2\php\php.ini，去掉以下行前面的分号：
#   ;extension=pdo_oci
# 改为：
#   extension=pdo_oci
# 同时需要安装 Oracle Instant Client 并配置系统 PATH
# 详见下方「数据库安装 → Oracle」章节
```

:::

### 可选扩展

::: code-group

```sh [Redis 缓存]
# 通过 PECL 安装
sudo pecl install redis

# 启用扩展
echo "extension=redis.so" | sudo tee /etc/php/8.2/mods-available/redis.ini
sudo phpenmod redis

# 验证
php -m | grep redis
```

```sh [Xdebug 调试]
# 仅开发环境安装
sudo pecl install xdebug

# 配置 php.ini
echo "[xdebug]" | sudo tee -a /etc/php/8.2/cli/php.ini
echo "zend_extension=xdebug" | sudo tee -a /etc/php/8.2/cli/php.ini
echo "xdebug.mode=debug" | sudo tee -a /etc/php/8.2/cli/php.ini
echo "xdebug.client_host=127.0.0.1" | sudo tee -a /etc/php/8.2/cli/php.ini
echo "xdebug.client_port=9003" | sudo tee -a /etc/php/8.2/cli/php.ini
```

```sh [OPcache 加速]
# 通常已随 PHP 安装，只需在 php.ini 中启用
# 生产环境必须启用
sudo sed -i 's/;opcache.enable=1/opcache.enable=1/' /etc/php/8.2/fpm/php.ini
```

:::

### 验证所有扩展

```bash
# 检查必需扩展
php -m | grep -E "pdo_mysql|mbstring|json|openssl|fileinfo|gd"

# 检查数据库扩展（按实际使用的数据库）
php -m | grep -E "pdo_mysql|pdo_pgsql|pdo_sqlsrv|pdo_oci|pdo_sqlite"
```

:::warning 扩展缺失会导致启动失败
如果上述命令输出为空，说明扩展未安装。最常见的缺失是 `pdo_mysql` 和 `gd`，缺少任何一个都会导致功能异常。
:::

## Composer 安装

::: code-group

```sh [Windows]
# 下载 Composer 安装器
# 访问 https://getcomposer.org/Composer-Setup.exe

# 运行安装程序，按提示完成安装
# 安装过程中会自动检测 PHP 路径

# 打开新的命令行窗口，验证
composer -V

# 配置中国镜像（可选）
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
```

```sh [Linux / macOS]
# 下载安装脚本
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"

# 全局安装
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer

# 删除安装脚本
php -r "unlink('composer-setup.php');"

# 验证
composer -V

# 配置中国镜像（可选，加速下载）
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
```

:::

### Composer 依赖清单

运行 `composer install` 后会安装以下核心依赖：

| 依赖 | 版本 | 说明 |
|------|------|------|
| `topthink/framework` | ^6.1.2 | ThinkPHP 框架 |
| `topthink/think-orm` | ^2.0 | 数据库 ORM |
| `topthink/think-filesystem` | ^1.0 | 文件系统 |
| `firebase/php-jwt` | ^6.4 | JWT 认证 |
| `phpoffice/phpspreadsheet` | ^5.10 | Excel 导入导出 |

开发依赖（`require-dev`）：

| 依赖 | 版本 | 说明 |
|------|------|------|
| `symfony/var-dumper` | ^6.0 | 调试变量打印（`dump()` 函数） |
| `topthink/think-trace` | ^1.0 | 调试追踪面板（页面右下角） |

## 数据库安装

项目支持五种数据库，按需选择一种即可。

| 数据库 | 推荐场景 | 难度 | XAMPP 自带 | 说明 |
|--------|---------|------|-----------|------|
| **MySQL** | 日常开发、中小项目 | ⭐ 低 | ✅ 是 | 默认推荐，开箱即用 |
| **PostgreSQL** | 需要 JSONB、全文检索 | ⭐⭐ 中 | ❌ 否 | 功能丰富，需单独安装 |
| **SQLite** | 快速演示、单元测试 | ⭐ 低 | ✅ 是 | 无需数据库服务，零配置 |
| **SQL Server** | 企业 Windows 环境 | ⭐⭐ 中 | 驱动自带 | 需单独安装数据库服务 |
| **Oracle** | 大型企业项目 | ⭐⭐⭐ 高 | 驱动自带 | 需安装 Instant Client |

::: tip 新手推荐
XAMPP 已集成 MySQL 数据库服务，安装 XAMPP 后无需再单独安装数据库。
:::

### MySQL 数据库

MySQL 是项目默认推荐的关系型数据库，XAMPP 已自带，开箱即用。

::: code-group

```sh [Windows]
# XAMPP 已自带 MySQL，无需额外安装
# 在 XAMPP 控制面板启动 MySQL 即可

# 确认扩展已启用（编辑 D:\xampp8.2\php\php.ini）：
#   extension=pdo_mysql
# 若前面有分号则去掉，保存后重启 XAMPP

# 创建数据库
D:\xampp8.2\mysql\bin\mysql.exe -u root -proot -e "CREATE DATABASE `rxthinkcmf.thinkphp8.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;"
```

```sh [macOS]
brew install mysql
brew services start mysql
sudo mysql_secure_installation

# 创建数据库
mysql -u root -proot -e "CREATE DATABASE `rxthinkcmf.thinkphp8.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;"
```

```sh [Ubuntu / Debian]
sudo apt install mysql-server
sudo systemctl start mysql
sudo systemctl enable mysql
sudo mysql_secure_installation

# 创建数据库
mysql -u root -proot -e "CREATE DATABASE `rxthinkcmf.thinkphp8.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;"
```

```sh [Rocky Linux / CentOS]
sudo dnf install mysql-server
sudo systemctl start mysqld
sudo systemctl enable mysqld
sudo mysql_secure_installation

# 创建数据库
mysql -u root -proot -e "CREATE DATABASE `rxthinkcmf.thinkphp8.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;"
```

:::

### PostgreSQL 数据库

PostgreSQL 功能强大，支持 JSONB、全文检索等高级特性，需单独安装。

::: code-group

```sh [Windows]
# 安装 PostgreSQL
# 访问 https://www.postgresql.org/download/windows/ 下载安装包
# 安装过程中记住设置的密码

# 确认扩展已启用（编辑 D:\xampp8.2\php\php.ini）：
#   extension=pdo_pgsql
#   extension=pgsql
# 若前面有分号则去掉，保存后重启 XAMPP

# 设置 postgres 密码（首次）
psql -U postgres -c "ALTER USER postgres WITH PASSWORD 'root';"

# 创建数据库
psql -U postgres -c "CREATE DATABASE \"rxthinkcmf.thinkphp8.elevue\" OWNER postgres ENCODING 'UTF8';"
```

```sh [macOS]
brew install postgresql
brew services start postgresql

# 设置 postgres 密码
sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'root';"

# 创建数据库
sudo -u postgres psql -c "CREATE DATABASE \"rxthinkcmf.thinkphp8.elevue\" OWNER postgres ENCODING 'UTF8';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE \"rxthinkcmf.thinkphp8.elevue\" TO postgres;"
```

```sh [Ubuntu / Debian]
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql

# 设置 postgres 密码
sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'root';"

# 创建数据库
sudo -u postgres psql -c "CREATE DATABASE \"rxthinkcmf.thinkphp8.elevue\" OWNER postgres ENCODING 'UTF8';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE \"rxthinkcmf.thinkphp8.elevue\" TO postgres;"
```

```sh [Rocky Linux / CentOS]
sudo dnf install postgresql-server
sudo postgresql-setup --initdb
sudo systemctl start postgresql

# 设置 postgres 密码
sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'root';"

# 创建数据库
sudo -u postgres psql -c "CREATE DATABASE \"rxthinkcmf.thinkphp8.elevue\" OWNER postgres ENCODING 'UTF8';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE \"rxthinkcmf.thinkphp8.elevue\" TO postgres;"
```

:::

### SQLite 数据库

SQLite 无需安装数据库服务器，数据存储在单个文件中，适合开发环境和小型项目。

::: code-group

```sh [Windows]
# XAMPP 已自带 SQLite 扩展，无需额外安装
# 只需创建数据库文件
mkdir D:\xampp\htdocs\runtime
echo. > D:\xampp\htdocs\runtime\database.sqlite

# 确认扩展已启用（编辑 D:\xampp8.2\php\php.ini）：
#   extension=pdo_sqlite
#   extension=sqlite3
# 若前面有分号则去掉，保存后重启 XAMPP

# .env 配置
# DATABASE.TYPE = sqlite
# DATABASE.DATABASE = D:/xampp8.2/htdocs/runtime/database.sqlite
```

```sh [macOS]
brew install php sqlite

# 创建数据库文件
mkdir -p /www/api/runtime
touch /www/api/runtime/database.sqlite
```

```sh [Ubuntu / Debian]
sudo apt install php8.2-sqlite3

# 创建数据库文件
mkdir -p /www/api/runtime
touch /www/api/runtime/database.sqlite
```

```sh [Rocky Linux / CentOS]
sudo dnf install php-sqlite3

# 创建数据库文件
mkdir -p /www/api/runtime
touch /www/api/runtime/database.sqlite
```

:::

### SQL Server 数据库

SQL Server 是微软商业数据库，XAMPP 已自带 pdo_sqlsrv 驱动，Windows 下开箱即用。

::: code-group

```sh [Windows]
# SQL Server 需单独安装（XAMPP 不自带数据库服务，但自带 PHP 驱动）
# 1. 下载安装 SQL Server Express：https://www.microsoft.com/zh-cn/sql-server/sql-server-downloads
# 2. XAMPP 已自带 pdo_sqlsrv 扩展，在 php.ini 中启用：
#    extension=php_sqlsrv_82_ts_x64.dll
#    extension=php_pdo_sqlsrv_82_ts_x64.dll

# 创建数据库
sqlcmd -S localhost -U sa -P root -Q "CREATE DATABASE [rxthinkcmf.thinkphp8.elevue] COLLATE Chinese_PRC_CI_AS"
```

```sh [macOS]
# macOS 不原生支持 SQL Server，建议使用 Docker
docker run -e "ACCEPT_EULA=Y" -e "SA_PASSWORD=root" \
  -p 1433:1433 --name sqlserver \
  -d mcr.microsoft.com/mssql/server:2022-latest

# 安装 PHP 扩展
pecl install pdo_sqlsrv

# 创建数据库
sqlcmd -S localhost -U sa -P root -Q "CREATE DATABASE [rxthinkcmf.thinkphp8.elevue] COLLATE Chinese_PRC_CI_AS"
```

```sh [Ubuntu / Debian]
# 1. 安装 SQL Server
curl -sSL https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
sudo add-apt-repository "$(wget -qO- https://packages.microsoft.com/config/ubuntu/22.04/mssql-server-2022.list)"
sudo apt update
sudo apt install -y mssql-server
sudo /opt/mssql/bin/mssql-conf setup

# 2. 安装命令行工具
sudo apt install -y mssql-tools18
echo 'export PATH="$PATH:/opt/mssql-tools18/bin"' >> ~/.bashrc
source ~/.bashrc

# 3. 安装 PHP 扩展
sudo pecl install pdo_sqlsrv
echo "extension=pdo_sqlsrv.so" | sudo tee /etc/php/8.2/mods-available/pdo_sqlsrv.ini
sudo phpenmod pdo_sqlsrv

# 创建数据库
sqlcmd -S localhost -U sa -P root -Q "CREATE DATABASE [rxthinkcmf.thinkphp8.elevue] COLLATE Chinese_PRC_CI_AS"
```

```sh [Rocky Linux / CentOS]
# 1. 安装 SQL Server
sudo curl -o /etc/yum.repos.d/mssql-server.repo https://packages.microsoft.com/config/rhel/8/mssql-server-2022.repo
sudo dnf install -y mssql-server
sudo /opt/mssql/bin/mssql-conf setup

# 2. 安装命令行工具
sudo curl -o /etc/yum.repos.d/msprod.repo https://packages.microsoft.com/config/rhel/8/prod.repo
sudo dnf install -y mssql-tools18
echo 'export PATH="$PATH:/opt/mssql-tools18/bin"' >> ~/.bashrc
source ~/.bashrc

# 3. 安装 PHP 扩展
sudo pecl install pdo_sqlsrv
echo "extension=pdo_sqlsrv.so" | sudo tee /etc/php.d/pdo_sqlsrv.ini

# 创建数据库
sqlcmd -S localhost -U sa -P root -Q "CREATE DATABASE [rxthinkcmf.thinkphp8.elevue] COLLATE Chinese_PRC_CI_AS"
```

:::

### Oracle 数据库

Oracle 是企业级商业数据库，需手动安装 Instant Client 和 pdo_oci 扩展。

::: code-group

```sh [Windows]
# XAMPP 已自带 php_pdo_oci.dll，只需安装 Oracle Instant Client 并在 php.ini 中启用

# 1. 安装 Oracle Instant Client
#    下载地址：https://www.oracle.com/database/technologies/instant-client/downloads.html
#    选择 Basic Package，x64，推荐 19c
#    解压到 C:\oracle\instantclient_19_20（⚠️ 避免空格与中文）

# 2. 配置系统环境变量
#    将 C:\oracle\instantclient_19_20 添加到系统 PATH

# 3. 安装 VC++ 运行库（必装）
#    下载：https://aka.ms/vc14/vc_redist.x64.exe

# 4. 启用扩展
#    编辑 D:\xampp8.2\php\php.ini，去掉分号：
#    extension=pdo_oci

# 5. 重启 XAMPP（完全关闭再启动）

# .env 配置
# DATABASE.TYPE = oracle
# DATABASE.HOSTNAME = 127.0.0.1
# DATABASE.DATABASE = rxthinkcmf.thinkphp8.elevue
# DATABASE.USERNAME = root
# DATABASE.PASSWORD = root
# DATABASE.HOSTPORT = 1521
```

```sh [macOS]
# Oracle 不原生支持 macOS，建议使用 Docker
docker run -d --name oracle-xe -p 1521:1521 \
  -e ORACLE_PWD=root \
  gvenzl/oracle-xe:21-slim

# 安装 PHP 扩展
pecl install pdo_oci
```

```sh [Ubuntu / Debian]
# 1. 安装 Oracle Database
sudo dpkg -i oracle-database-xe-21c-1.0-1.x86_64.deb
sudo /etc/init.d/oracle-xe-21c configure

# 2. 安装 Oracle Instant Client
sudo dpkg -i oracle-instantclient-basic-*.deb
sudo dpkg -i oracle-instantclient-devel-*.deb

# 3. 安装 PHP 扩展
sudo pecl install pdo_oci
echo "extension=pdo_oci.so" | sudo tee /etc/php/8.2/mods-available/pdo_oci.ini
sudo phpenmod pdo_oci

# 4. 创建表空间和用户
sqlplus system/root@localhost:1521/XE <<EOF
CREATE TABLESPACE "rxthinkcmf_thinkphp8_elevue" DATAFILE '/opt/oracle/oradata/XE/rxthinkcmf_thinkphp8_elevue.dbf' SIZE 100M AUTOEXTEND ON NEXT 100M;
CREATE USER "root" IDENTIFIED BY "root" DEFAULT TABLESPACE "rxthinkcmf_thinkphp8_elevue";
GRANT CONNECT, RESOURCE, CREATE VIEW TO "root";
GRANT UNLIMITED TABLESPACE TO "root";
EXIT;
EOF
```

```sh [Rocky Linux / CentOS]
# 1. 安装 Oracle Database
sudo rpm -ivh oracle-database-xe-21c-1.0-1.x86_64.rpm
sudo /etc/init.d/oracle-xe-21c configure

# 2. 安装 Oracle Instant Client
sudo rpm -ivh oracle-instantclient-basic-*.rpm
sudo rpm -ivh oracle-instantclient-devel-*.rpm

# 3. 安装 PHP 扩展
sudo pecl install pdo_oci
echo "extension=pdo_oci.so" | sudo tee /etc/php/8.2/mods-available/pdo_oci.ini
sudo phpenmod pdo_oci

# 4. 创建表空间和用户
sqlplus system/root@localhost:1521/XE <<EOF
CREATE TABLESPACE "rxthinkcmf_thinkphp8_elevue" DATAFILE '/opt/oracle/oradata/XE/rxthinkcmf_thinkphp8_elevue.dbf' SIZE 100M AUTOEXTEND ON NEXT 100M;
CREATE USER "root" IDENTIFIED BY "root" DEFAULT TABLESPACE "rxthinkcmf_thinkphp8_elevue";
GRANT CONNECT, RESOURCE, CREATE VIEW TO "root";
GRANT UNLIMITED TABLESPACE TO "root";
EXIT;
EOF
```

:::

## Redis 安装（可选）

::: code-group

```sh [Windows]
# ─── 1. 安装 Redis 服务端 ──────────────────────────────────

# 下载 Redis for Windows
# 访问 https://github.com/tporadowski/redis/releases 下载 .msi 安装包
# 注：该仓库已归档但仍可用；也可使用 Memurai（Redis Windows 兼容方案）
# 安装完成后，Redis 会作为 Windows 服务自动启动

# 验证 Redis 服务
redis-cli ping
# 输出：PONG

# ─── 2. 启用 PHP Redis 扩展 ────────────────────────────────

# XAMPP 已自带 php_redis.dll（位于 D:\xampp8.2\php\ext\）
# 编辑 D:\xampp8.2\php\php.ini，去掉以下行前面的分号：
#   extension=redis
# 若没有该行，则手动添加：
#   extension=redis

# 同时建议确认 GD 扩展已启用（验证码功能依赖）：
#   extension=gd

# 保存后重启 XAMPP

# ─── 3. 验证 ───────────────────────────────────────────────

# 命令行验证扩展已加载
D:\xampp8.2\php\php.exe -m | findstr -i "redis"

# 验证 PHP 可连接 Redis
D:\xampp8.2\php\php.exe -r "var_dump(class_exists('Redis'));"
# 输出：bool(true)
```

```sh [macOS]
brew install redis
brew services start redis

# 验证
redis-cli ping
```

```sh [Ubuntu / Debian]
sudo apt install redis-server
sudo systemctl start redis
sudo systemctl enable redis

# 验证
redis-cli ping
# 输出：PONG
```

```sh [Rocky Linux / CentOS]
sudo dnf install redis
sudo systemctl start redis
sudo systemctl enable redis

# 验证
redis-cli ping
```

:::

## Node.js / pnpm 安装

::: code-group

```sh [Windows (直接安装)]
# 下载 Node.js 安装包
# 访问 https://nodejs.org/ 下载 LTS 版本（22.x）

# 运行安装程序，按提示完成安装

# 打开新的命令行窗口，验证
node -v                                # 查看 Node.js 版本（需 22+）
npm -v                                 # 查看 npm 版本（随 Node.js 一起安装）

# 安装 pnpm 包管理器（比 npm 更快、磁盘占用更少）
# -g → 全局安装（所有项目可用）
npm install -g pnpm

# 验证
pnpm -v                                # 查看 pnpm 版本
```

```sh [Windows (nvm-windows)]
# nvm-windows 是 Windows 下的 Node.js 版本管理工具
# 可以轻松切换多个 Node.js 版本

# ─── 1. 安装 nvm-windows ───────────────────────────────────

# 方式一：下载安装包（推荐）
# 访问 https://github.com/coreybutler/nvm-windows/releases
# 下载最新版 nvm-setup.exe，运行安装

# 方式二：使用 winget 安装
winget install CoreyButler.NVMforWindows

# 安装完成后，打开新的命令行窗口验证
nvm version

# ─── 2. 安装 Node.js ──────────────────────────────────────

# 查看可用的 Node.js 版本
nvm list available

# 安装 LTS 版本
nvm install 22

# 使用该版本
nvm use 22

# 验证
node -v    # v22.x.x
npm -v     # 10.x.x

# ─── 3. 安装 pnpm ─────────────────────────────────────────

npm install -g pnpm

# 验证
pnpm -v    # 12.x.x

# ─── 4. 常用命令 ──────────────────────────────────────────

# 查看已安装的版本
nvm list

# 切换版本
nvm use 18

# 安装其他版本
nvm install 20

# 卸载版本
nvm uninstall 18
```

```sh [Linux / macOS (nvm)]
# 安装 nvm（Node.js 版本管理器）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc  # 或 source ~/.zshrc

# 安装 Node.js 22
nvm install 22
nvm use 22

# 验证
node -v    # v22.x.x
npm -v     # 9.x.x

# 安装 pnpm
npm install -g pnpm

# 验证
pnpm -v    # 12.x.x
```

:::tip 镜像配置
如果安装依赖速度较慢，建议为 pnpm 和 npm 均配置国内镜像源。
:::

```sh
# pnpm 镜像
pnpm config set registry https://registry.npmmirror.com

# npm 镜像
npm config set registry https://registry.npmmirror.com

# 验证配置
pnpm config get registry
npm config get registry
# 输出：https://registry.npmmirror.com/

# 如遇 SSL 证书问题（如企业代理环境），可临时关闭严格校验
npm config set strict-ssl false
```

配置完成后可通过 `pnpm config list` 或 `npm config list` 查看完整配置：

```sh
$ npm config list
; "user" config from C:\Users\home\.npmrc

registry = "https://registry.npmmirror.com/"
strict-ssl = false

; node bin location = C:\Program Files\nodejs\node.exe
; node version = v22.18.0
; npm version = 11.12.1
```

### 前端依赖清单

运行 `cd ui && pnpm install` 后会安装以下核心依赖：

| 依赖 | 版本 | 说明 |
|------|------|------|
| `vue` | ^3.4.27 | 核心框架 |
| `element-plus` | ^2.7.4 | UI 组件库 |
| `pinia` | ^2.1.7 | 状态管理 |
| `vue-router` | ^4.3.2 | 路由管理 |
| `axios` | ^0.27.2 | HTTP 请求 |
| `typescript` | ^4.9.5 | 类型系统 |
| `vite` | ^3.2.10 | 构建工具 |
| `tinymce` | 5.10.3 | 富文本编辑器 |
| `echarts` | ^5.5.0 | 图表库 |
| `tailwindcss` | ^3.4.3 | CSS 框架 |
| `xlsx` | ^0.18.5 | Excel 处理 |
| `@element-plus/icons-vue` | ^2.3.1 | ElementPlus 图标 |
| `dayjs` | ^1.11.11 | 日期处理 |
| `lodash` | ^4.17.21 | 工具函数库 |

## 开发工具推荐

### PhpStorm

专业的 PHP IDE，内置 Xdebug 调试、Composer 管理、数据库工具。

- 下载：https://www.jetbrains.com/phpstorm/
- 推荐插件：ThinkPHP、Vue.js

### VS Code

轻量级编辑器，通过插件支持 PHP 和前端开发。

推荐插件：

| 插件 | 说明 |
|------|------|
| PHP Intelephense | PHP 代码提示 |
| PHP Debug | Xdebug 调试 |
| Vue - Official | Vue 3 支持 |
| ESLint | 代码检查 |
| Prettier | 代码格式化 |

### 数据库管理工具

| 工具 | 支持数据库 | 说明 |
|------|-----------|------|
| Navicat | MySQL/PG/Oracle/SQLServer/SQLite | 商业，功能强大 |
| DBeaver | 全部 | 开源免费 |
| phpMyAdmin | MySQL | Web 界面 |
| HeidiSQL | MySQL/PG/SQLServer | Windows 免费 |

## Xdebug 配置（PhpStorm）

::: tip 前置条件
请先完成 Xdebug 扩展的安装，详见上方「PHP 扩展安装 → 可选扩展 → Xdebug 调试」。
:::

::: code-group

```ini [php.ini 配置]
[xdebug]
zend_extension=xdebug
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.idekey=PHPSTORM
```

```text [PhpStorm 配置步骤]
1. Settings → PHP → Debug → Xdebug 端口设为 9003
2. Settings → PHP → Servers → 添加 localhost:80
3. 点击电话图标（Start Listening for PHP Debug Connections）
4. 在代码中设置断点
5. 浏览器访问页面，PhpStorm 会自动停在断点处
```

:::

## 环境验证清单

完成以上所有安装后，逐项验证：

```bash
# =============================================================================
# 环境验证清单（逐项检查，全部通过即可开始开发）
# =============================================================================

# ─── 1. PHP 版本和扩展 ────────────────────────────────────
php -v                                    # 查看版本，需 >= 8.2
php -m | grep -E "pdo_mysql|mbstring|gd"  # 检查必需扩展是否已加载

# ─── 2. Composer 包管理器 ──────────────────────────────────
composer -V                               # 正常输出版本号即为安装成功

# ─── 3. 数据库连接 ────────────────────────────────────────
# MySQL：查询数据库列表，确认项目数据库存在
mysql -u root -proot -e "SHOW DATABASES;" | grep rxthinkcmf

# ─── 4. Node.js / pnpm ────────────────────────────────────
node -v                                   # 查看版本，需 22+
pnpm -v                                   # 正常输出版本号即为安装成功

# ─── 5. Redis 缓存（可选）────────────────────────────────
redis-cli ping                            # 输出 PONG 表示 Redis 服务正常
```

::: tip 全部通过？
如果以上命令均正常输出，说明环境搭建成功，可以进入项目启动阶段。
:::

### 一键环境检查脚本

将以下脚本保存为项目根目录的 `check_env.php`，运行 `php check_env.php` 即可一次性检查所有环境：

```php
<?php
/**
 * check_env.php — 一键环境检查脚本
 * 用法：php check_env.php
 * 用途：自动检查 PHP 版本、扩展、Composer 依赖、Node.js 环境是否满足项目要求
 */

// =============================================================================
// 1. PHP 版本检查
// =============================================================================
// PHP_VERSION → 当前 PHP 版本号
// version_compare() → 比较版本号是否 >= 8.2.0
echo "=== PHP 版本检查 ===\n";
echo "PHP Version: " . PHP_VERSION . (version_compare(PHP_VERSION, '8.2.0', '>=') ? " ✓" : " ✗ 需要 8.2+") . "\n";

// =============================================================================
// 2. 必需扩展检查
// =============================================================================
// extension_loaded() → 检查指定扩展是否已加载
echo "\n=== 必需扩展检查 ===\n";
$required = ['pdo_mysql', 'mbstring', 'json', 'openssl', 'fileinfo', 'gd'];
foreach ($required as $ext) {
    $loaded = extension_loaded($ext);
    echo "  $ext: " . ($loaded ? "✓ 已安装" : "✗ 未安装") . "\n";
}

// =============================================================================
// 3. 可选扩展检查
// =============================================================================
echo "\n=== 可选扩展检查 ===\n";
$optional = ['redis', 'xdebug', 'opcache'];
foreach ($optional as $ext) {
    $loaded = extension_loaded($ext);
    echo "  $ext: " . ($loaded ? "✓ 已安装" : "- 未安装（可选）") . "\n";
}

// =============================================================================
// 4. Composer 依赖检查
// =============================================================================
// 读取 composer.json，检查 vendor/ 下的依赖是否已安装
echo "\n=== Composer 依赖检查 ===\n";
$composerJson = file_get_contents(__DIR__ . '/composer.json');
if ($composerJson) {
    $data = json_decode($composerJson, true);
    $require = $data['require'] ?? [];
    foreach ($require as $pkg => $ver) {
        if ($pkg === 'php') continue;       // 跳过 PHP 版本要求
        $path = __DIR__ . '/vendor/' . $pkg;
        echo "  $pkg $ver: " . (is_dir($path) ? "✓ 已安装" : "✗ 未安装（运行 composer install）") . "\n";
    }
} else {
    echo "  ⚠ 未找到 composer.json\n";
}

// =============================================================================
// 5. Node.js 环境检查
// =============================================================================
// shell_exec() → 执行系统命令并返回输出
// 2>nul → 将错误输出重定向到空设备（Windows 下隐藏 "命令未找到" 的错误）
echo "\n=== Node.js 环境检查 ===\n";
$nodeVer = trim(shell_exec('node -v 2>nul') ?: '');
$pnpmVer = trim(shell_exec('pnpm -v 2>nul') ?: '');
echo "  node: " . ($nodeVer ? "$nodeVer ✓" : "✗ 未安装") . "\n";
echo "  pnpm: " . ($pnpmVer ? "$pnpmVer ✓" : "✗ 未安装（运行 npm install -g pnpm）") . "\n";

echo "\n=== 完成 ===\n";
```