Files

T

2026-10-11 19:06:33 +08:00

35 KiB

Raw Permalink Blame History

2.1 开发环境准备

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

安装流程总览

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 环境搭建完成 phpredis 扩展与虚拟主机配置，可跳过本章大部分手动安装步骤。 :::

PHP 安装

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

方式一：Laragon（Windows 推荐）

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

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 环境搭建。

方式二：XAMPP

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

::: code-group

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

# 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

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

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

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

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

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

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

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

# 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

# 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 环境搭建

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

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

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

:::

验证所有扩展

# 检查必需扩展
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

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

依赖	版本	说明
`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

# 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.naivevue\` 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.laravel13.naivevue\` 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.laravel13.naivevue\` 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.laravel13.naivevue\` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;"

:::

创建后的 .env 配置：

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

PostgreSQL 数据库

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

::: code-group

# 安装 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.naivevue\" 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.laravel13.naivevue\" OWNER postgres ENCODING 'UTF8';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE \"rxthinkcmf.laravel13.naivevue\" 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.laravel13.naivevue\" OWNER postgres ENCODING 'UTF8';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE \"rxthinkcmf.laravel13.naivevue\" 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.laravel13.naivevue\" OWNER postgres ENCODING 'UTF8';"

:::

.env 配置：

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

SQLite 数据库

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

::: code-group

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

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

# 创建数据库文件（如缺失）
touch database/database.sqlite

:::

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

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

:::warning SQLite 仅适合开发与测试。完整初始化数据请导入 document/sqlite/rxthinkcmf.laravel13.naivevue.sql（五种数据库各有专用脚本，按 document/<数据库类型>/ 分组，见 2.5 数据库初始化）。 :::

SQL Server 数据库

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

::: code-group

# 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.naivevue] 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.laravel13.naivevue] 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.3/mods-available/pdo_sqlsrv.ini
sudo phpenmod pdo_sqlsrv

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

:::

.env 配置：

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

Oracle 数据库

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

::: code-group

# 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.naivevue
# DB_USERNAME=root
# DB_PASSWORD=root

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

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

# 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

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

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

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

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

:::

Redis 密码（可选但需同步）

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

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

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

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

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

# 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

# 安装 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 均配置国内镜像源。 :::

# 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

前端依赖清单

进入 ui/ 目录执行 pnpm install 后会安装以下核心依赖：

依赖	版本	说明
`vue`	^3.5.1	核心框架
`naive-ui`	^2.40.0	UI 组件库
`pinia`	^2.2.2	状态管理
`vue-router`	^4.4.3	路由管理
`axios`	^1.7.7	HTTP 请求
`typescript`	^4.9.5	类型系统
`vite`	^5.4.3	构建工具
`tinymce`	5.10.3	富文本编辑器
`@vueup/vue-quill`	1.0.0-beta.8	富文本编辑器（Quill）
`echarts`	^5.5.1	图表库
`tailwindcss`	^3.4.10	CSS 框架
`xlsx`	^0.17.5	Excel 处理
`@vicons/antd`	^0.10.0	图标库
`date-fns`	^2.30.0	日期处理
`lodash-es`	^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

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

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

:::

环境验证清单

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

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

# ─── 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 后端服务启动）。 :::

一键环境检查脚本

将以下脚本保存为项目根目录的 check_env.php，运行 php check_env.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";

35 KiB Raw Permalink Blame History Unescape Escape

2.1 开发环境准备

安装流程总览

PHP 安装

方式一：Laragon（Windows 推荐）

方式二：XAMPP

方式三：包管理器安装

PHP 扩展安装

必需扩展

数据库扩展（按需安装）

Redis 扩展（必需）

可选扩展

验证所有扩展

Composer 安装

Composer 依赖清单

数据库安装

MySQL 数据库

PostgreSQL 数据库

SQLite 数据库

SQL Server 数据库

Oracle 数据库

Redis 安装（必需）

Redis 密码（可选但需同步）

Node.js / pnpm 安装

前端依赖清单

开发工具推荐

PhpStorm

VS Code

数据库管理工具

Xdebug 配置（PhpStorm）

环境验证清单

一键环境检查脚本

35 KiB

Raw Permalink Blame History