Files

T

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

12 KiB

Raw Permalink Blame History

2.2 Laragon 环境搭建

:::tip 概述本项目推荐使用 Laragon 在 Windows 下搭建本地开发环境（Apache + PHP 8.3 + MySQL + Redis）。本页基于实际部署记录整理，涵盖 Laragon 目录结构、hosts 域名解析、Apache 虚拟主机配置、phpredis 扩展安装、php.ini 关键配置、Redis 密码与故障排查。完成本页后，即可进入 2.3 后端服务启动。 :::

环境概况

项目	说明
操作系统	Windows 10 / 11
集成环境	Laragon（如 `D:\laragon`）
Web 服务器	Apache 2.4（Laragon 内置，mod_php 方式）
PHP	8.3.x Win64 TS（线程安全），项目要求 ≥ 8.3
数据库	MySQL 8.x（Laragon 内置）
缓存	Redis（Laragon 内置，`127.0.0.1:6379`）

关键目录：

D:\laragon\www\                                 # 站点根目录（Apache 主 DocumentRoot）
D:\laragon\bin\apache\httpd-2.4.x-...\          # Apache 主目录（下称 $HTTPD_HOME）
D:\laragon\bin\php\php-8.3.x-Win32-vs16-x64\    # PHP 8.3 目录（下称 $PHP_HOME）
D:\laragon\www\RXThinkCMF_Laravel13_NaiveVue\     # 项目根目录（下称 $PROJECT）

:::warning PATH 中的 php 版本陷阱 Laragon 默认 shell PATH 指向的可能是旧版 PHP（如 7.3），直接执行 php artisan 会报 requires PHP >= 8.3。执行 artisan、pint、composer 时必须使用 8.3 的完整路径：

$PHP_HOME\php.exe artisan list
$PHP_HOME\php.exe vendor\bin\pint --test

:::

安装 PHP 8.3

打开 Laragon 菜单 PHP → Version，选择 8.3.x；
列表中没有 8.3 时，手动下载 php-8.3.x-Win32-vs16-x64.zip（TS 线程安全版，Laragon 的 Apache 以 mod_php 方式运行，必须用 TS），解压到 D:\laragon\bin\php\ 下，重启 Laragon 后重新选择；
验证版本与线程安全类型：

$PHP_HOME\php.exe -v
# PHP 8.3.x (ts) ...

$PHP_HOME\php.exe -i | findstr "Thread Safety"
# Thread Safety => enabled        ← TS（Apache mod_php 需要）

$PHP_HOME\php.exe -i | findstr "extension_dir"
# extension_dir => D:/laragon/bin/php/php-8.3.x-Win32-vs16-x64/ext   ← 记下扩展目录

hosts 域名解析

编辑 C:\Windows\System32\drivers\etc\hosts（管理员权限）：

127.0.0.1 admin.laravel13.naivevue file.laravel13.naivevue

域名	用途
`admin.laravel13.naivevue`	应用入口（DocumentRoot 指向项目 `public/`）
`file.laravel13.naivevue`	附件目录（DocumentRoot 指向项目 `uploads/`）

同系列项目域名格式为 admin.<项目>.<前端品牌>，如 admin.laravel13.antdvue、admin.laravel13.naivevue。

Apache 虚拟主机配置

配置位置

httpd.conf 末尾有两处 Include，均可放置虚拟主机：

IncludeOptional "D:/laragon/etc/apache2/sites-enabled/*.conf"   # Laragon 自动生成
Include "conf/vhost/*.conf"                                     # 手动配置（本项目在此）

本项目使用 $HTTPD_HOME\conf\vhost\laravel13.conf。

配置模板（Directory 块缺一不可）

# 项目应用本地虚拟主机配置
<VirtualHost *:80>
    ServerAdmin rxthinkcmf@163.com
    ServerName admin.laravel13.naivevue
    DocumentRoot "D:\laragon\www\RXThinkCMF_Laravel13_NaiveVue\public"
    ErrorLog "logs/laravel13-error.log"
    CustomLog "logs/laravel13-access.log" common
    <Directory "D:\laragon\www\RXThinkCMF_Laravel13_NaiveVue\public">
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

# 项目附件目录本地虚拟主机配置
<VirtualHost *:80>
    ServerName file.laravel13.naivevue
    DocumentRoot "D:\laragon\www\RXThinkCMF_Laravel13_NaiveVue\uploads"
    ErrorLog "logs/laravel13-error.log"
    CustomLog "logs/laravel13-access.log" common
    <Directory "D:\laragon\www\RXThinkCMF_Laravel13_NaiveVue\uploads">
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

为什么 Directory 块必须写（404 根因）

主 httpd.conf 中的默认设置为 AllowOverride None（全局忽略 .htaccess）。Apache 的 <Directory> 写在某个 <VirtualHost> 内部时只对该虚拟主机生效，因此 vhost 必须自带 <Directory> 块，把本虚拟主机范围内的 AllowOverride 覆盖为 All，Laravel 的 public/.htaccess（URL 重写规则）才能生效。

症状特征（识别此问题的关键）：

GET /              → 200 正常（DirectoryIndex 命中物理文件 index.php）
GET /api/captcha   → 404，且是 Apache 原生 HTML 404 页
                     <title>404 Not Found</title>（不是 Laravel 的 JSON 响应）

解读：物理文件能访问、非物理 URL 无法重写进 index.php，说明请求根本没有进入 Laravel。只要 404 页面是 Apache 原生的，问题一定在 Web 服务器配置，而不是 Laravel 路由。

配置校验与重启

# 改动配置后必做：校验语法（输出 Syntax OK 即通过；AH00112 警告可忽略）
$HTTPD_HOME\bin\httpd.exe -t

# Apache 未注册为 Windows 服务，-k restart 会报 "No installed service"，需手动重启：
taskkill //F //IM httpd.exe
cmd //c start "" "D:\laragon\bin\apache\httpd-2.4.x-...\bin\httpd.exe"

# 验证进程（应看到 2 个 httpd.exe：父进程 + 工作进程）
tasklist //FI "IMAGENAME eq httpd.exe"

:::tip Laragon 菜单 Apache → Reload 亦可；手动部署环境下以上命令最可靠。 :::

安装 phpredis 扩展

项目强依赖 Redis（验证码、JWT 会话、字典缓存），PHP 必须安装 redis 扩展，否则报 Class "Redis" not found。

判断线程安全类型（决定下载哪个包）

$PHP_HOME\php.exe -i | findstr "Thread Safety"
# Thread Safety => enabled   → TS 包（Laragon 的 Apache 用 TS）
# Thread Safety => disabled  → NTS 包（php-fpm 用）

下载

官方 Windows 扩展仓库（windows.php.net 会 302 跳转到 downloads.php.net）：

https://downloads.php.net/~windows/pecl/releases/redis/
# 目录按版本号分子目录：6.0.0/ 6.1.0/ 6.2.0/ 6.3.0/ ...

文件名命名规则（四个要素必须全部匹配）：

php_redis-{扩展版本}-php-{PHP主次版本}-{ts|nts}-vs16-{x64|x86}.zip

本次实际下载（PHP 8.3 + TS + 64 位 + VS16 编译器）：
https://downloads.php.net/~windows/pecl/releases/redis/6.3.0/php_redis-6.3.0-8.3-ts-vs16-x64.zip

安装

# 解压后将 php_redis.dll 复制到扩展目录
copy php_redis.dll D:\laragon\bin\php\php-8.3.x-Win32-vs16-x64\ext\

php.ini 配置

编辑 $PHP_HOME\php.ini（mod_php 与 CLI 共用同一份），在扩展区按字母序新增一行：

extension_dir = "D:/laragon/bin/php/php-8.3.x-Win32-vs16-x64/ext"
...
;extension=pgsql
extension=redis          ← 新增此行（PHP 8 写法：不带 php_ 前缀和 .dll 后缀）
;extension=shmop

:::danger 常见坑

写成 extension=php_redis.dll 是 PHP 5 时代的旧写法，PHP 8 下报错；
只改 php.ini-development / php.ini-production 无效，PHP 加载的是 php.ini；
改完必须重启 Apache（mod_php 常驻进程，不会热加载）。 :::

验证

# CLI 验证（应输出 redis）
$PHP_HOME\php.exe -m | findstr redis

# HTTP 验证（重启 Apache 后调用依赖 Redis 的接口，见下方「部署验证清单」）

php.ini 关键配置

$PHP_HOME\php.ini 中与本项目相关的关键配置：

配置项	建议值	说明
`extension` 系列	按需启用	项目必需：`pdo_mysql`、`mbstring`、`gd`、`bcmath`、`zip`、`redis`、`openssl`、`fileinfo`、`curl`；跨库迁移目标为 PostgreSQL 时另启用 `pdo_pgsql`
`memory_limit`	`256M`	Excel 导出等大内存场景
`max_execution_time`	`60`	导入导出超时上限
`upload_max_filesize` / `post_max_size`	`50M`	与 `.env` 中 `FILE_MAX_SIZE` 配合（业务限制更小）
`date.timezone`	`Asia/Shanghai`	与应用时区一致
`opcache.enable`	`1`	本地开发可保持 `opcache.validate_timestamps=1`，改代码即时生效

修改后重启 Apache 生效。

Redis 密码配置

状态确认

tasklist //FI "IMAGENAME eq redis-server.exe"     # 进程
netstat -an | findstr ":6379"                     # 应看到 127.0.0.1:6379 LISTENING

设置密码（实际踩坑记录）

:::warning Redis 无密码直连可用；一旦 Redis 侧设置了 requirepass 而 .env 未同步（或 .env 配了 REDIS_PASSWORD 而 Redis 侧没设密码），Laravel 所有 Redis 操作（验证码、JWT 会话、限流）会全部失败。验证码接口此时返回「缓存服务(Redis)连接失败，请检查 Redis 配置（地址、端口、密码）后重试」，真实错误（如 ERR AUTH ...）记录在日志 验证码写入 Redis 失败 中。 :::

处理步骤（缺一不可）：

Redis 服务端设置密码（redis.conf 的 requirepass 或 CONFIG SET requirepass）；
.env 同步配置：

REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=你的密码        ← 原为 null，必须改
REDIS_PORT=6379

清除配置缓存并重启 Apache：

$PHP_HOME\php.exe artisan config:clear

单独验证 Redis 连通（绕开业务代码）

$PHP_HOME\php.exe 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 秒自动过期）

部署验证清单

按顺序全部通过即环境就绪：

□ $PHP_HOME\php.exe -v                     → PHP 8.3.x (ts)
□ $PHP_HOME\php.exe -m | findstr redis     → redis
□ httpd.exe -t                             → Syntax OK
□ tasklist 查看 redis-server.exe           → 进程存在，6379 LISTENING
□ curl http://admin.laravel13.naivevue/api/captcha
     → {"code":0,"ok":true,"msg":"操作成功","data":{...}}
□ curl -X POST http://admin.laravel13.naivevue/api/login
     → {"code":1,"ok":false,"msg":"参数验证失败","data":{...}}   （路由已通）

验证码接口返回 code=0 的 JSON 即部署成功——它同时验证了 Apache 重写、PHP 8.3、Redis 连通三条链路。

常见问题

症状	原因	处理
`/` 正常，`/api/*` 返回 Apache 原生 HTML 404	vhost 缺 `<Directory>` 块，`.htaccess` 被忽略	补 `AllowOverride All` 块，`httpd -t` 后重启 Apache
`Class "Redis" not found`	PHP 缺 redis 扩展	装 `php_redis.dll` + `php.ini` 加 `extension=redis`
验证码接口返回「缓存服务(Redis)连接失败…」	Redis 密码不匹配或服务未启	日志搜 `验证码写入 Redis 失败` 看真实错误；`.env` 配 `REDIS_PASSWORD`，tinker 单测 Redis 连通
artisan/pint 报 requires PHP >= 8.3	shell PATH 的 php 是旧版	用 `$PHP_HOME\php.exe` 完整路径调用
`httpd -k restart` 报 No installed service	Apache 未注册 Windows 服务	`taskkill` 后重新启动 `httpd.exe`
改了配置 / 扩展不生效	mod_php 常驻不热加载	必须重启 Apache

12 KiB Raw Permalink Blame History Unescape Escape