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）

方式二：XAMPP

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

WindowsmacOS

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

方式三：包管理器安装

Ubuntu / DebianRocky Linux / AlmaLinuxCentOS / RHELmacOS (Homebrew)

# 添加 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 扩展」

数据库扩展（按需安装）

# 大多数安装方式已包含
# 如缺失：
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。

Windows (Laragon / XAMPP)Linux / macOS

# 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

可选扩展

Xdebug 调试OPcache 加速

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

验证所有扩展

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"

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 依赖清单

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

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

MySQL 数据库

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

Windows (Laragon)macOSUbuntu / DebianRocky Linux / CentOS

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

ini

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、全文检索等高级特性，需单独安装。

WindowsmacOSUbuntu / DebianRocky Linux / CentOS

# 安装 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';"

ini

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。

WindowsmacOS / Linux

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

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

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

ini

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

SQL Server 数据库

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

WindowsmacOSUbuntu / DebianRocky Linux / CentOS

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

ini

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 扩展。

WindowsmacOSUbuntu / DebianRocky Linux / CentOS

# 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 初始化）

Redis 安装（必需）

# 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 密码（可选但需同步）

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

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

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

# 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

前端依赖清单

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

VS Code

插件	说明
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）

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.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 表示扩展已加载

一键环境检查脚本

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

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）

环境验证清单

一键环境检查脚本

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） ​

环境验证清单 ​

一键环境检查脚本 ​

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）

环境验证清单

一键环境检查脚本