2.1 开发环境准备

概述

本章指导您从零搭建开发环境，包括 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 安装

版本要求

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

方式一：XAMPP（推荐新手）

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

WindowsmacOS

# 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"

# 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"

方式二：包管理器安装

Ubuntu / DebianRocky Linux / AlmaLinuxCentOS / RHELmacOS (Homebrew)

# 添加 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"

# 启用 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

# 启用 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

# 安装 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 安装

数据库扩展（按需安装）

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

sudo apt install php8.2-pgsql        # Ubuntu
sudo dnf install php-pgsql           # Rocky Linux

sudo apt install php8.2-sqlite3      # Ubuntu
sudo dnf install php-sqlite3         # Rocky Linux

# 安装 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

# 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」章节

可选扩展

Redis 缓存Xdebug 调试OPcache 加速

# 通过 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

# 仅开发环境安装
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

# 通常已随 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"

扩展缺失会导致启动失败

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

Composer 安装

WindowsLinux / macOS

# 下载 Composer 安装器
# 访问 https://getcomposer.org/Composer-Setup.exe

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

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

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

# 下载安装脚本
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

新手推荐

XAMPP 已集成 MySQL 数据库服务，安装 XAMPP 后无需再单独安装数据库。

MySQL 数据库

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

WindowsmacOSUbuntu / DebianRocky Linux / CentOS

# 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.thinkphp6.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;"

brew install mysql
brew services start mysql
sudo mysql_secure_installation

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

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.thinkphp6.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;"

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.thinkphp6.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;"

PostgreSQL 数据库

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

WindowsmacOSUbuntu / DebianRocky Linux / CentOS

# 安装 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.thinkphp6.elevue\" OWNER postgres ENCODING 'UTF8';"

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.thinkphp6.elevue\" OWNER postgres ENCODING 'UTF8';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE \"rxthinkcmf.thinkphp6.elevue\" TO postgres;"

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.thinkphp6.elevue\" OWNER postgres ENCODING 'UTF8';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE \"rxthinkcmf.thinkphp6.elevue\" TO postgres;"

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.thinkphp6.elevue\" OWNER postgres ENCODING 'UTF8';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE \"rxthinkcmf.thinkphp6.elevue\" TO postgres;"

SQLite 数据库

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

WindowsmacOSUbuntu / DebianRocky Linux / CentOS

# 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

brew install php sqlite

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

sudo apt install php8.2-sqlite3

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

sudo dnf install php-sqlite3

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

SQL Server 数据库

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

WindowsmacOSUbuntu / DebianRocky Linux / CentOS

# 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.thinkphp6.elevue] COLLATE Chinese_PRC_CI_AS"

# 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.thinkphp6.elevue] COLLATE Chinese_PRC_CI_AS"

# 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.thinkphp6.elevue] COLLATE Chinese_PRC_CI_AS"

# 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.thinkphp6.elevue] COLLATE Chinese_PRC_CI_AS"

Oracle 数据库

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

WindowsmacOSUbuntu / DebianRocky Linux / CentOS

# 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.thinkphp6.elevue
# DATABASE.USERNAME = root
# DATABASE.PASSWORD = root
# DATABASE.HOSTPORT = 1521

# 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

# 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_thinkphp6_elevue" DATAFILE '/opt/oracle/oradata/XE/rxthinkcmf_thinkphp6_elevue.dbf' SIZE 100M AUTOEXTEND ON NEXT 100M;
CREATE USER "root" IDENTIFIED BY "root" DEFAULT TABLESPACE "rxthinkcmf_thinkphp6_elevue";
GRANT CONNECT, RESOURCE, CREATE VIEW TO "root";
GRANT UNLIMITED TABLESPACE TO "root";
EXIT;
EOF

# 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_thinkphp6_elevue" DATAFILE '/opt/oracle/oradata/XE/rxthinkcmf_thinkphp6_elevue.dbf' SIZE 100M AUTOEXTEND ON NEXT 100M;
CREATE USER "root" IDENTIFIED BY "root" DEFAULT TABLESPACE "rxthinkcmf_thinkphp6_elevue";
GRANT CONNECT, RESOURCE, CREATE VIEW TO "root";
GRANT UNLIMITED TABLESPACE TO "root";
EXIT;
EOF

Redis 安装（可选）

WindowsmacOSUbuntu / DebianRocky Linux / CentOS

# ─── 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)

brew install redis
brew services start redis

# 验证
redis-cli ping

sudo apt install redis-server
sudo systemctl start redis
sudo systemctl enable redis

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

sudo dnf install redis
sudo systemctl start redis
sudo systemctl enable redis

# 验证
redis-cli ping

Node.js / pnpm 安装

Windows (直接安装)Windows (nvm-windows)Linux / macOS (nvm)

# 下载 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 版本

# 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

# 安装 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

镜像配置

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

# 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 查看完整配置：

$ 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	Element Plus 图标
`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）

前置条件

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

php.ini 配置PhpStorm 配置步骤

ini

[xdebug]
zend_extension=xdebug
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.idekey=PHPSTORM

text

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 服务正常

全部通过？

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

一键环境检查脚本

将以下脚本保存为项目根目录的 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";

Become a sponsor

企业级中台解决方案

企业级中台解决方案

2.1 开发环境准备 ​

安装流程总览 ​

PHP 安装 ​

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

方式二：包管理器安装 ​

PHP 扩展安装 ​

必需扩展 ​

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

可选扩展 ​

验证所有扩展 ​

Composer 安装 ​

Composer 依赖清单 ​

数据库安装 ​

MySQL 数据库 ​

PostgreSQL 数据库 ​

SQLite 数据库 ​

SQL Server 数据库 ​

Oracle 数据库 ​

Redis 安装（可选） ​

Node.js / pnpm 安装 ​

前端依赖清单 ​

开发工具推荐 ​

PhpStorm ​

VS Code ​

数据库管理工具 ​

Xdebug 配置（PhpStorm） ​

环境验证清单 ​

一键环境检查脚本 ​

2.1 开发环境准备

安装流程总览

PHP 安装

方式一：XAMPP（推荐新手）

方式二：包管理器安装

PHP 扩展安装

必需扩展

数据库扩展（按需安装）

可选扩展

验证所有扩展

Composer 安装

Composer 依赖清单

数据库安装

MySQL 数据库

PostgreSQL 数据库

SQLite 数据库

SQL Server 数据库

Oracle 数据库

Redis 安装（可选）

Node.js / pnpm 安装

前端依赖清单

开发工具推荐

PhpStorm

VS Code

数据库管理工具

Xdebug 配置（PhpStorm）

环境验证清单

一键环境检查脚本