# 2.1 开发环境准备

:::tip 概述
本章指导您从零搭建开发环境，包括 PHP、Composer、数据库、Redis、Node.js 的安装与配置。项目支持 MySQL、PostgreSQL、SQL Server、Oracle、SQLite 五种数据库（`document/` 下各有专用初始化脚本），其中 **Redis 为必需组件**（JWT 会话、权限缓存、验证码、字典缓存均依赖）。
:::

## 安装流程总览

```mermaid
graph TD
    A[开始] --> B[安装 PHP 8.3]
    B --> C[安装 Composer]
    C --> D[安装 Redis]
    D --> E{选择数据库}
    E --> E1[MySQL]
    E --> E2[PostgreSQL]
    E --> E3[SQLite]
    E --> E4[SQL Server]
    E --> E5[Oracle]
    E1 --> F[安装 Node.js 22.18.0 / pnpm]
    E2 --> F
    E3 --> F
    E4 --> F
    E5 --> F
    F --> G[配置开发工具]
    G --> H[环境就绪 ✅]

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

:::tip Windows 用户推荐
Windows 环境推荐直接使用 **Laragon 集成安装**（Apache + PHP 8.3 + MySQL + Redis 一体），并参考 [2.2 Laragon 环境搭建](/zh/quickstart/laragon.html) 完成 phpredis 扩展与虚拟主机配置，可跳过本章大部分手动安装步骤。
:::

## PHP 安装

:::warning 版本要求
项目要求 PHP >= 8.3（composer.json `^8.3`），推荐使用 8.3.x 稳定版。
:::

### 方式一：Laragon（Windows 推荐）

Laragon 是 Windows 下的集成化开发环境（Apache + PHP + MySQL + Redis），本项目即基于 Laragon 部署验证。

```text
1. 访问 https://laragon.org/ 下载并安装 Laragon
2. 菜单 PHP → Version 选择 8.3.x（列表没有时手动下载 php-8.3.x-Win32-vs16-x64.zip 解压到 bin\php\）
3. 验证：
   $PHP_HOME\php.exe -v        → PHP 8.3.x (ts)
   $PHP_HOME\php.exe -i | findstr "Thread Safety"  → enabled（TS）
```

详细配置（虚拟主机、phpredis 扩展、php.ini）见 [2.2 Laragon 环境搭建](/zh/quickstart/laragon.html)。

### 方式二：XAMPP

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

::: code-group

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

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

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

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

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

```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|redis"
```

:::

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

::: code-group

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

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

# 验证安装
php -v

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

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

# 启用 PHP 8.3 模块
sudo dnf module reset php -y
sudo dnf module enable php:remi-8.3 -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.3
sudo yum module reset php -y
sudo yum module enable php:remi-8.3 -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.3
brew install php@8.3

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

# 验证安装
php -v

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

:::

## PHP 扩展安装

### 必需扩展

| 扩展 | 用途 | 安装说明 |
|------|------|----------|
| `pdo_mysql` | MySQL 数据库驱动 | 已随 php-mysql 安装 |
| `mbstring` | 多字节字符串处理（Laravel 框架依赖） | 已随 PHP 安装 |
| `json` | JSON 编解码 | PHP 8.3 自带 |
| `openssl` | JWT 签名 / HTTPS | PHP 8.3 自带 |
| `fileinfo` | 文件 MIME 类型检测（上传安全） | PHP 8.3 自带 |
| `gd` | 图片验证码生成 | 已随 php-gd 安装 |
| `bcmath` | 高精度数学运算（phpspreadsheet 依赖） | 已随 php-bcmath 安装 |
| `zip` | ZIP 压缩（phpspreadsheet 读写 xlsx） | 已随 php-zip 安装 |
| **`redis`** | **Redis 扩展（phpredis，必需）** | 见下方「Redis 扩展」 |

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

::: code-group

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

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

# Windows（Laragon）：ext\php_pdo_pgsql.dll 与 libpq.dll 随 PHP 自带，
# 只需在 $PHP_HOME\php.ini 扩展区启用：
#   extension=pdo_pgsql
# CLI 每次进程重读 php.ini，无需重启；mod_php 需重启 Apache
# 未启用时执行 php artisan db:migrate --dst-type=pgsql 报 could not find driver
```

```sh [SQLite]
sudo apt install php8.3-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.3/mods-available/pdo_sqlsrv.ini
sudo phpenmod pdo_sqlsrv
```

```sh [Oracle]
# 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.3/mods-available/pdo_oci.ini
sudo phpenmod pdo_oci

# Windows：下载对应 PHP 版本的 php_pdo_oci.dll 放入 ext\，
# 在 php.ini 中启用：extension=pdo_oci
# 同时需要安装 Oracle Instant Client 并配置系统 PATH
# 详见下方「数据库安装 → Oracle」章节
```

:::

### Redis 扩展（必需）

项目强依赖 Redis，PHP 必须加载 phpredis 扩展，否则报 `Class "Redis" not found`。

::: code-group

```sh [Windows (Laragon / XAMPP)]
# Windows 下无 pecl 编译环境，手动安装 DLL：
# 1. 判断线程安全类型（Laragon 的 Apache 用 TS）：
$PHP_HOME\php.exe -i | findstr "Thread Safety"     # enabled → TS 包

# 2. 下载对应构建包（四个要素必须全部匹配：扩展版本 / PHP 主次版本 / ts|nts / x64|x86）：
#    https://downloads.php.net/~windows/pecl/releases/redis/
#    例：php_redis-6.3.0-8.3-ts-vs16-x64.zip

# 3. 解压后将 php_redis.dll 复制到扩展目录 ext\

# 4. php.ini 扩展区按字母序新增（PHP 8 写法，不带 php_ 前缀和 .dll 后缀）：
#    extension=redis

# 5. 重启 Apache（mod_php 常驻不热加载）
# 详细图文步骤见 2.2 Laragon 环境搭建
```

```sh [Linux / macOS]
# 通过 PECL 安装
sudo pecl install redis

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

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

:::

### 可选扩展

::: code-group

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

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

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

:::

### 验证所有扩展

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

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

:::warning 扩展缺失会导致启动失败
如果上述命令输出为空，说明扩展未安装。最常见缺失是 `pdo_mysql`、`gd` 和 `redis`——`redis` 缺失会导致验证码、登录等核心功能直接不可用。
:::

## 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` 后会安装以下核心依赖：

| 依赖 | 版本 | 说明 |
|------|------|------|
| `laravel/framework` | ^13.0 | Laravel 框架 |
| `firebase/php-jwt` | ^7.1 | JWT 令牌签发与解析 |
| `phpoffice/phpspreadsheet` | ^5.10 | Excel 导入导出 |
| `zoujingli/ip2region` | ^3.0 | IP 归属地解析 |

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

| 依赖 | 版本 | 说明 |
|------|------|------|
| `laravel/pint` | ^1.27 | 代码格式化（提交前 `./vendor/bin/pint`） |
| `laravel/pail` | ^1.2 | 实时日志流（`composer dev` 内置） |
| `phpunit/phpunit` | ^12.5 | 测试框架（`composer test`） |
| `fakerphp/faker` | ^1.23 | 测试数据生成 |
| `mockery/mockery` | ^1.6 | 测试 Mock |

## 数据库安装

项目支持五种数据库，按需选择一种即可，`document/` 下均提供对应初始化脚本。

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

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

### MySQL 数据库

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

::: code-group

```sh [Windows (Laragon)]
# Laragon 控制面板启动 MySQL 即可

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

# 创建数据库
D:\laragon\bin\mysql\bin\mysql.exe -u root -proot -e "CREATE DATABASE \`rxthinkcmf.laravel13.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.laravel13.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.laravel13.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.laravel13.elevue\` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;"
```

:::

创建后的 `.env` 配置：

```ini
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=rxthinkcmf.laravel13.elevue
DB_USERNAME=root
DB_PASSWORD=root
DB_PREFIX=laravel_
```

### PostgreSQL 数据库

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

::: code-group

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

# 确认扩展已启用（编辑 $PHP_HOME\php.ini）：
#   extension=pdo_pgsql
#   extension=pgsql
# 若前面有分号则去掉，保存后重启环境

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

# 创建数据库
psql -U postgres -c "CREATE DATABASE \"rxthinkcmf.laravel13.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.laravel13.elevue\" OWNER postgres ENCODING 'UTF8';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE \"rxthinkcmf.laravel13.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.laravel13.elevue\" OWNER postgres ENCODING 'UTF8';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE \"rxthinkcmf.laravel13.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.laravel13.elevue\" OWNER postgres ENCODING 'UTF8';"
```

:::

`.env` 配置：

```ini
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=rxthinkcmf.laravel13.elevue
DB_USERNAME=postgres
DB_PASSWORD=root
DB_PREFIX=laravel_
```

### SQLite 数据库

SQLite 无需安装数据库服务器，数据存储在单个文件中，适合开发环境和单元测试。项目根目录 `database/` 下已自带 `database.sqlite`。

::: code-group

```sh [Windows]
# 确认扩展已启用（编辑 $PHP_HOME\php.ini）：
#   extension=pdo_sqlite
#   extension=sqlite3
# 若前面有分号则去掉，保存后重启环境

# 若文件不存在，创建数据库文件
echo. > database\database.sqlite
```

```sh [macOS / Linux]
# 创建数据库文件（如缺失）
touch database/database.sqlite
```

:::

`.env` 配置（Laravel 默认即 sqlite）：

```ini
DB_CONNECTION=sqlite
# DB_DATABASE 指向 database/database.sqlite（默认值，无需修改）
DB_PREFIX=laravel_
```

:::warning
SQLite 仅适合开发与测试。完整初始化数据请导入 `document/sqlite/rxthinkcmf.laravel13.elevue.sql`（五种数据库各有专用脚本，按 `document/<数据库类型>/` 分组，见 [2.5 数据库初始化](/zh/quickstart/database-init.html)）。
:::

### SQL Server 数据库

SQL Server 是微软商业数据库，Windows 下安装 ODBC 驱动后开箱即用。

::: code-group

```sh [Windows]
# 1. 下载安装 SQL Server Express：https://www.microsoft.com/zh-cn/sql-server/sql-server-downloads
# 2. 安装 Microsoft ODBC Driver（默认已随 SQL Server 安装）
# 3. 启用 PHP 扩展（Windows 无 pecl：下载 Windows_5.13.3RTW.zip，PHP 8.3 起步对应 83 系列）
#    解压后取两个 DLL 复制到 ext\，再在 php.ini 启用（本项目 PHP 8.3 TS x64）：
#    extension=php_sqlsrv_83_ts_x64.dll
#    extension=php_pdo_sqlsrv_83_ts_x64.dll
#    完整 DLL 清单与选择规则见 7.6 数据库迁移工具 → 驱动安装与环境配置

# 创建数据库
sqlcmd -S localhost -U sa -P root -Q "CREATE DATABASE [rxthinkcmf.laravel13.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.laravel13.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.3/mods-available/pdo_sqlsrv.ini
sudo phpenmod pdo_sqlsrv

# 创建数据库
sqlcmd -S localhost -U sa -P root -Q "CREATE DATABASE [rxthinkcmf.laravel13.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.laravel13.elevue] COLLATE Chinese_PRC_CI_AS"
```

:::

`.env` 配置：

```ini
DB_CONNECTION=sqlsrv
DB_HOST=127.0.0.1
DB_PORT=1433
DB_DATABASE=rxthinkcmf.laravel13.elevue
DB_USERNAME=sa
DB_PASSWORD=root
DB_PREFIX=laravel_
```

### Oracle 数据库

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

::: code-group

```sh [Windows]
# 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. 启用扩展
#    编辑 $PHP_HOME\php.ini，添加：
#    extension=pdo_oci

# 5. 重启 Web 服务（完全关闭再启动）

# .env 配置
# DB_CONNECTION=oracle
# DB_HOST=127.0.0.1
# DB_PORT=1521
# DB_DATABASE=rxthinkcmf.laravel13.elevue
# DB_USERNAME=root
# DB_PASSWORD=root
```

```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.3/mods-available/pdo_oci.ini
sudo phpenmod pdo_oci

# 4. 创建表空间和用户（详见 2.5 数据库初始化 → Oracle 初始化）
```

```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.d/pdo_oci.ini

# 4. 创建表空间和用户（详见 2.5 数据库初始化 → Oracle 初始化）
```

:::

:::warning Oracle 常见坑
- Instant Client 必须解压到**固定路径**（PATH 写的是绝对路径，移动/改名会导致加载失败），推荐 `C:\oracle\instantclient_19_20`（避免空格与中文）；
- 必须安装 VC++ 2015-2022 Redistributable（x64）；
- PATH 修改发生在 Web 服务启动**之后**时，需完全重启 Web 服务才会生效；
- 命令行 `php -m` 能看到 pdo_oci 但 phpinfo() 里没有 → Web 服务读取的是启动时的 PATH，完全重启即可。
:::

## Redis 安装（必需）

:::danger Redis 是必需组件
验证码、JWT 双令牌会话、权限缓存、字典缓存、会话/队列驱动均依赖 Redis。未安装或密码不匹配时，登录、验证码等核心功能将直接不可用。
:::

::: code-group

```sh [Windows (Laragon)]
# Laragon 内置 Redis：菜单 Redis → 启动即可（127.0.0.1:6379）

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

# PHP 侧需安装 php_redis.dll 扩展（见上方「Redis 扩展」与 2.2 Laragon 环境搭建）

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

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

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

```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
```

:::

### Redis 密码（可选但需同步）

设置了 `requirepass` 时，`.env` 必须同步配置，**缺一不可**：

```ini
REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=你的密码        # Redis 无密码时保持 null
REDIS_PORT=6379
```

改完执行 `php artisan config:clear` 并重启 Web 服务。连通性单测：

```bash
php artisan tinker --execute="try { \Illuminate\Support\Facades\Redis::setex('test:key', 10, 'ok'); echo 'OK: '.\Illuminate\Support\Facades\Redis::get('test:key'); } catch (\Throwable \$e) { echo get_class(\$e).': '.\$e->getMessage(); }"
# 输出 OK: ok 即连接正常（测试键 10 秒自动过期）
```

## Node.js / pnpm 安装

:::code-group

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

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

# 打开新的命令行窗口，验证
node -v                                # 查看 Node.js 版本（本环境 v22.18.0，需 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.18.0
npm -v     # 10.x.x

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

npm install -g pnpm

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

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

# 查看已安装的版本
nvm list

# 切换版本
nvm use 22

# 安装其他版本
nvm install 20

# 卸载版本
nvm uninstall 20
```

```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.18.0
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
```

### 前端依赖清单

进入前端仓库执行 `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 | Element Plus 图标 |
| `dayjs` | ^1.11.11 | 日期处理 |
| `lodash` | ^4.17.21 | 工具函数库 |

## 开发工具推荐

### PhpStorm

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

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

### VS Code

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

推荐插件：

| 插件 | 说明 |
|------|------|
| PHP Intelephense | PHP 代码提示 |
| PHP Debug | Xdebug 调试 |
| Laravel Extra Intelephense | Laravel 门面/路由提示 |
| 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.3
php -m | grep -E "pdo_mysql|mbstring|gd|redis"      # 检查必需扩展是否已加载

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

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

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

# ─── 5. Redis 缓存（必需）─────────────────────────────────
redis-cli ping                                      # 输出 PONG 表示 Redis 服务正常
php -m | grep redis                                 # 输出 redis 表示扩展已加载
```

::: tip 全部通过？
如果以上命令均正常输出，说明环境搭建成功，可以进入项目启动阶段（见 [2.3 后端服务启动](/zh/quickstart/backend-start.html)）。
:::

### 一键环境检查脚本

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

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

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

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

// =============================================================================
// 3. 可选扩展检查
// =============================================================================
echo "\n=== 可选扩展检查 ===\n";
$optional = ['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. Redis 服务连通检查
// =============================================================================
// 扩展已加载时尝试 PING，验证服务端可用
echo "\n=== Redis 服务检查 ===\n";
if (extension_loaded('redis')) {
    try {
        $r = new Redis();
        $r->connect('127.0.0.1', 6379, 2);
        echo "  service: ✓ 连接正常（" . $r->ping() . "）\n";
    } catch (Throwable $e) {
        echo "  service: ✗ 连接失败（" . $e->getMessage() . "）\n";
    }
} else {
    echo "  extension: ✗ phpredis 扩展未安装\n";
}

// =============================================================================
// 6. 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";
```