73 lines
38 KiB
JavaScript
73 lines
38 KiB
JavaScript
import{_ as a,o as i,c as e,a2 as t}from"./chunks/framework.B-QBKwc1.js";const c=JSON.parse('{"title":"Laragon 环境搭建","description":"本项目推荐使用 Laragon 在 Windows 下搭建本地开发环境（Apache + PHP 8.3 + MySQL + Redis）。","frontmatter":{},"headers":[],"relativePath":"zh/quickstart/laragon.md","filePath":"zh/quickstart/laragon.md"}'),n={name:"zh/quickstart/laragon.md"};function l(p,s,h,d,o,k){return i(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="_2-2-Laragon-环境搭建" tabindex="-1">2.2 Laragon 环境搭建 <a class="header-anchor" href="#_2-2-Laragon-环境搭建" aria-label="Permalink to "2.2 Laragon 环境搭建""></a></h1><div class="tip custom-block"><p class="custom-block-title">概述</p><p>本项目推荐使用 Laragon 在 Windows 下搭建本地开发环境（Apache + PHP 8.3 + MySQL + Redis）。本页基于实际部署记录整理，涵盖 Laragon 目录结构、hosts 域名解析、Apache 虚拟主机配置、phpredis 扩展安装、php.ini 关键配置、Redis 密码与故障排查。完成本页后，即可进入 <a href="/zh/quickstart/backend-start.html">2.3 后端服务启动</a>。</p></div><h2 id="环境概况" tabindex="-1">环境概况 <a class="header-anchor" href="#环境概况" aria-label="Permalink to "环境概况""></a></h2><table tabindex="0"><thead><tr><th>项目</th><th>说明</th></tr></thead><tbody><tr><td>操作系统</td><td>Windows 10 / 11</td></tr><tr><td>集成环境</td><td>Laragon（如 <code>D:\\laragon</code>）</td></tr><tr><td>Web 服务器</td><td>Apache 2.4（Laragon 内置，mod_php 方式）</td></tr><tr><td>PHP</td><td>8.3.x Win64 <strong>TS（线程安全）</strong>，项目要求 ≥ 8.3</td></tr><tr><td>数据库</td><td>MySQL 8.x（Laragon 内置）</td></tr><tr><td>缓存</td><td>Redis（Laragon 内置，<code>127.0.0.1:6379</code>）</td></tr></tbody></table><p><strong>关键目录：</strong></p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span>D:\\laragon\\www\\ # 站点根目录（Apache 主 DocumentRoot）</span></span>
|
||
<span class="line"><span>D:\\laragon\\bin\\apache\\httpd-2.4.x-...\\ # Apache 主目录（下称 $HTTPD_HOME）</span></span>
|
||
<span class="line"><span>D:\\laragon\\bin\\php\\php-8.3.x-Win32-vs16-x64\\ # PHP 8.3 目录（下称 $PHP_HOME）</span></span>
|
||
<span class="line"><span>D:\\laragon\\www\\RXThinkCMF_Laravel13_EleVue\\ # 项目根目录（下称 $PROJECT）</span></span></code></pre></div><div class="warning custom-block"><p class="custom-block-title">PATH 中的 php 版本陷阱</p><p>Laragon 默认 shell PATH 指向的可能是旧版 PHP（如 7.3），直接执行 <code>php artisan</code> 会报 <code>requires PHP >= 8.3</code>。执行 artisan、pint、composer 时<strong>必须使用 8.3 的完整路径</strong>：</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span style="--shiki-dark:#BF9EEE;--shiki-light:#B07D48;">$PHP_HOME</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\p</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">hp.exe artisan list</span></span>
|
||
<span class="line"><span style="--shiki-dark:#BF9EEE;--shiki-light:#B07D48;">$PHP_HOME</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\p</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">hp.exe vendor</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\b</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">in</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\p</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">int --test</span></span></code></pre></div></div><h2 id="安装-PHP-8-3" tabindex="-1">安装 PHP 8.3 <a class="header-anchor" href="#安装-PHP-8-3" aria-label="Permalink to "安装 PHP 8.3""></a></h2><ol><li>打开 Laragon 菜单 <strong>PHP → Version</strong>，选择 8.3.x；</li><li>列表中没有 8.3 时，手动下载 <code>php-8.3.x-Win32-vs16-x64.zip</code>（<strong>TS 线程安全版</strong>，Laragon 的 Apache 以 mod_php 方式运行，必须用 TS），解压到 <code>D:\\laragon\\bin\\php\\</code> 下，重启 Laragon 后重新选择；</li><li>验证版本与线程安全类型：</li></ol><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span style="--shiki-dark:#BF9EEE;--shiki-light:#B07D48;">$PHP_HOME</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\p</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">hp.exe -v</span></span>
|
||
<span class="line"><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"># PHP 8.3.x (ts) ...</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-dark:#BF9EEE;--shiki-light:#B07D48;">$PHP_HOME</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\p</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">hp.exe -i </span><span style="--shiki-dark:#F286C4;--shiki-light:#AB5959;">|</span><span style="--shiki-dark:#62E884;--shiki-light:#59873A;"> findstr</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;"> "</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;">Thread Safety</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;">"</span></span>
|
||
<span class="line"><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"># Thread Safety => enabled ← TS（Apache mod_php 需要）</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-dark:#BF9EEE;--shiki-light:#B07D48;">$PHP_HOME</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\p</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">hp.exe -i </span><span style="--shiki-dark:#F286C4;--shiki-light:#AB5959;">|</span><span style="--shiki-dark:#62E884;--shiki-light:#59873A;"> findstr</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;"> "</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;">extension_dir</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;">"</span></span>
|
||
<span class="line"><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"># extension_dir => D:/laragon/bin/php/php-8.3.x-Win32-vs16-x64/ext ← 记下扩展目录</span></span></code></pre></div><h2 id="hosts-域名解析" tabindex="-1">hosts 域名解析 <a class="header-anchor" href="#hosts-域名解析" aria-label="Permalink to "hosts 域名解析""></a></h2><p>编辑 <code>C:\\Windows\\System32\\drivers\\etc\\hosts</code>（管理员权限）：</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span>127.0.0.1 admin.laravel13.elevue file.laravel13.elevue</span></span></code></pre></div><table tabindex="0"><thead><tr><th>域名</th><th>用途</th></tr></thead><tbody><tr><td><code>admin.laravel13.elevue</code></td><td>应用入口（DocumentRoot 指向项目 <code>public/</code>）</td></tr><tr><td><code>file.laravel13.elevue</code></td><td>附件目录（DocumentRoot 指向项目 <code>uploads/</code>）</td></tr></tbody></table><p>同系列项目域名格式为 <code>admin.<项目>.<前端品牌></code>，如 <code>admin.laravel13.antdvue</code>、<code>admin.laravel13.naivevue</code>。</p><h2 id="Apache-虚拟主机配置" tabindex="-1">Apache 虚拟主机配置 <a class="header-anchor" href="#Apache-虚拟主机配置" aria-label="Permalink to "Apache 虚拟主机配置""></a></h2><h3 id="配置位置" tabindex="-1">配置位置 <a class="header-anchor" href="#配置位置" aria-label="Permalink to "配置位置""></a></h3><p><code>httpd.conf</code> 末尾有两处 Include，均可放置虚拟主机：</p><div class="language-apache vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">apache</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;">IncludeOptional</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;"> "D:/laragon/etc/apache2/sites-enabled/*.conf" # Laragon 自动生成</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;">Include</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;"> "conf/vhost/*.conf" # 手动配置（本项目在此）</span></span></code></pre></div><p>本项目使用 <code>$HTTPD_HOME\\conf\\vhost\\laravel13.conf</code>。</p><h3 id="配置模板-Directory-块缺一不可-" tabindex="-1">配置模板（Directory 块缺一不可） <a class="header-anchor" href="#配置模板-Directory-块缺一不可-" aria-label="Permalink to "配置模板（Directory 块缺一不可）""></a></h3><div class="language-apache vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">apache</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"># 项目应用本地虚拟主机配置</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F6F6F4;--shiki-light:#999999;"><</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#59873A;">VirtualHost</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> *:80</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#999999;">></span></span>
|
||
<span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;"> ServerAdmin</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;"> rxthinkcmf@</span><span style="--shiki-dark:#BF9EEE;--shiki-light:#2F798A;">163</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">.com</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;"> ServerName</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;"> admin.laravel13.elevue</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;"> DocumentRoot</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;"> "D:\\laragon\\www\\RXThinkCMF_Laravel13_EleVue\\public"</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;"> ErrorLog</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;"> "logs/laravel13-error.log"</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;"> CustomLog</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;"> "logs/laravel13-access.log" common</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F6F6F4;--shiki-light:#999999;"> <</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#59873A;">Directory</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> "D:\\laragon\\www\\RXThinkCMF_Laravel13_EleVue\\public"</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#999999;">></span></span>
|
||
<span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;"> AllowOverride</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;"> All</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;"> Require</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;"> all granted</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F6F6F4;--shiki-light:#999999;"> </</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#59873A;">Directory</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#999999;">></span></span>
|
||
<span class="line"><span style="--shiki-dark:#F6F6F4;--shiki-light:#999999;"></</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#59873A;">VirtualHost</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#999999;">></span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"># 项目附件目录本地虚拟主机配置</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F6F6F4;--shiki-light:#999999;"><</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#59873A;">VirtualHost</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> *:80</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#999999;">></span></span>
|
||
<span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;"> ServerName</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;"> file.laravel13.elevue</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;"> DocumentRoot</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;"> "D:\\laragon\\www\\RXThinkCMF_Laravel13_EleVue\\uploads"</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;"> ErrorLog</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;"> "logs/laravel13-error.log"</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;"> CustomLog</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;"> "logs/laravel13-access.log" common</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F6F6F4;--shiki-light:#999999;"> <</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#59873A;">Directory</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> "D:\\laragon\\www\\RXThinkCMF_Laravel13_EleVue\\uploads"</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#999999;">></span></span>
|
||
<span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;"> AllowOverride</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;"> All</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;"> Require</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;"> all granted</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F6F6F4;--shiki-light:#999999;"> </</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#59873A;">Directory</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#999999;">></span></span>
|
||
<span class="line"><span style="--shiki-dark:#F6F6F4;--shiki-light:#999999;"></</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#59873A;">VirtualHost</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#999999;">></span></span></code></pre></div><h3 id="为什么-Directory-块必须写-404-根因-" tabindex="-1">为什么 Directory 块必须写（404 根因） <a class="header-anchor" href="#为什么-Directory-块必须写-404-根因-" aria-label="Permalink to "为什么 Directory 块必须写（404 根因）""></a></h3><p>主 <code>httpd.conf</code> 中的默认设置为 <code>AllowOverride None</code>（全局忽略 <code>.htaccess</code>）。Apache 的 <code><Directory></code> 写在某个 <code><VirtualHost></code> 内部时<strong>只对该虚拟主机生效</strong>，因此 vhost 必须自带 <code><Directory></code> 块，把本虚拟主机范围内的 <code>AllowOverride</code> 覆盖为 <code>All</code>，Laravel 的 <code>public/.htaccess</code>（URL 重写规则）才能生效。</p><p><strong>症状特征（识别此问题的关键）：</strong></p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span>GET / → 200 正常（DirectoryIndex 命中物理文件 index.php）</span></span>
|
||
<span class="line"><span>GET /api/captcha → 404，且是 Apache 原生 HTML 404 页</span></span>
|
||
<span class="line"><span> <title>404 Not Found</title>（不是 Laravel 的 JSON 响应）</span></span></code></pre></div><p>解读：物理文件能访问、非物理 URL 无法重写进 <code>index.php</code>，说明请求根本没有进入 Laravel。<strong>只要 404 页面是 Apache 原生的，问题一定在 Web 服务器配置，而不是 Laravel 路由。</strong></p><h3 id="配置校验与重启" tabindex="-1">配置校验与重启 <a class="header-anchor" href="#配置校验与重启" aria-label="Permalink to "配置校验与重启""></a></h3><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"># 改动配置后必做：校验语法（输出 Syntax OK 即通过；AH00112 警告可忽略）</span></span>
|
||
<span class="line"><span style="--shiki-dark:#BF9EEE;--shiki-light:#B07D48;">$HTTPD_HOME</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\b</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">in</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\h</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">ttpd.exe -t</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"># Apache 未注册为 Windows 服务，-k restart 会报 "No installed service"，需手动重启：</span></span>
|
||
<span class="line"><span style="--shiki-dark:#62E884;--shiki-light:#59873A;">taskkill</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> //F</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> //IM</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> httpd.exe</span></span>
|
||
<span class="line"><span style="--shiki-dark:#62E884;--shiki-light:#59873A;">cmd</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> //c</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> start</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;"> ""</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;"> "</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;">D:\\laragon\\bin\\apache\\httpd-2.4.x-...\\bin\\httpd.exe</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;">"</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"># 验证进程（应看到 2 个 httpd.exe：父进程 + 工作进程）</span></span>
|
||
<span class="line"><span style="--shiki-dark:#62E884;--shiki-light:#59873A;">tasklist</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> //FI</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;"> "</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;">IMAGENAME eq httpd.exe</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;">"</span></span></code></pre></div><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>Laragon 菜单 <strong>Apache → Reload</strong> 亦可；手动部署环境下以上命令最可靠。</p></div><h2 id="安装-phpredis-扩展" tabindex="-1">安装 phpredis 扩展 <a class="header-anchor" href="#安装-phpredis-扩展" aria-label="Permalink to "安装 phpredis 扩展""></a></h2><p>项目强依赖 Redis（验证码、JWT 会话、字典缓存），PHP 必须安装 redis 扩展，否则报 <code>Class "Redis" not found</code>。</p><h3 id="判断线程安全类型-决定下载哪个包-" tabindex="-1">判断线程安全类型（决定下载哪个包） <a class="header-anchor" href="#判断线程安全类型-决定下载哪个包-" aria-label="Permalink to "判断线程安全类型（决定下载哪个包）""></a></h3><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span style="--shiki-dark:#BF9EEE;--shiki-light:#B07D48;">$PHP_HOME</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\p</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">hp.exe -i </span><span style="--shiki-dark:#F286C4;--shiki-light:#AB5959;">|</span><span style="--shiki-dark:#62E884;--shiki-light:#59873A;"> findstr</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;"> "</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;">Thread Safety</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;">"</span></span>
|
||
<span class="line"><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"># Thread Safety => enabled → TS 包（Laragon 的 Apache 用 TS）</span></span>
|
||
<span class="line"><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"># Thread Safety => disabled → NTS 包（php-fpm 用）</span></span></code></pre></div><h3 id="下载" tabindex="-1">下载 <a class="header-anchor" href="#下载" aria-label="Permalink to "下载""></a></h3><p>官方 Windows 扩展仓库（<code>windows.php.net</code> 会 302 跳转到 <code>downloads.php.net</code>）：</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span>https://downloads.php.net/~windows/pecl/releases/redis/</span></span>
|
||
<span class="line"><span># 目录按版本号分子目录：6.0.0/ 6.1.0/ 6.2.0/ 6.3.0/ ...</span></span></code></pre></div><p>文件名命名规则（<strong>四个要素必须全部匹配</strong>）：</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span>php_redis-{扩展版本}-php-{PHP主次版本}-{ts|nts}-vs16-{x64|x86}.zip</span></span>
|
||
<span class="line"><span></span></span>
|
||
<span class="line"><span>本次实际下载（PHP 8.3 + TS + 64 位 + VS16 编译器）：</span></span>
|
||
<span class="line"><span>https://downloads.php.net/~windows/pecl/releases/redis/6.3.0/php_redis-6.3.0-8.3-ts-vs16-x64.zip</span></span></code></pre></div><h3 id="安装" tabindex="-1">安装 <a class="header-anchor" href="#安装" aria-label="Permalink to "安装""></a></h3><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"># 解压后将 php_redis.dll 复制到扩展目录</span></span>
|
||
<span class="line"><span style="--shiki-dark:#62E884;--shiki-light:#59873A;">copy</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> php_redis.dll</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> D:</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\l</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;">aragon</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\b</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;">in</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\p</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;">hp</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\p</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;">hp-8.3.x-Win32-vs16-x64</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\e</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;">xt</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\</span></span></code></pre></div><h3 id="php-ini-配置" tabindex="-1">php.ini 配置 <a class="header-anchor" href="#php-ini-配置" aria-label="Permalink to "php.ini 配置""></a></h3><p>编辑 <code>$PHP_HOME\\php.ini</code>（mod_php 与 CLI 共用同一份），在扩展区按字母序新增一行：</p><div class="language-ini vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ini</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;">extension_dir</span><span style="--shiki-dark:#F286C4;--shiki-light:#999999;"> =</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;"> "</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;">D:/laragon/bin/php/php-8.3.x-Win32-vs16-x64/ext</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;">"</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">...</span></span>
|
||
<span class="line"><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;">;extension=pgsql</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;">extension</span><span style="--shiki-dark:#F286C4;--shiki-light:#999999;">=</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">redis ← 新增此行（PHP 8 写法：不带 php_ 前缀和 .dll 后缀）</span></span>
|
||
<span class="line"><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;">;extension=shmop</span></span></code></pre></div><div class="danger custom-block"><p class="custom-block-title">常见坑</p><ul><li>写成 <code>extension=php_redis.dll</code> 是 PHP 5 时代的旧写法，PHP 8 下报错；</li><li>只改 <code>php.ini-development</code> / <code>php.ini-production</code> 无效，PHP 加载的是 <code>php.ini</code>；</li><li><strong>改完必须重启 Apache</strong>（mod_php 常驻进程，不会热加载）。</li></ul></div><h3 id="验证" tabindex="-1">验证 <a class="header-anchor" href="#验证" aria-label="Permalink to "验证""></a></h3><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"># CLI 验证（应输出 redis）</span></span>
|
||
<span class="line"><span style="--shiki-dark:#BF9EEE;--shiki-light:#B07D48;">$PHP_HOME</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\p</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">hp.exe -m </span><span style="--shiki-dark:#F286C4;--shiki-light:#AB5959;">|</span><span style="--shiki-dark:#62E884;--shiki-light:#59873A;"> findstr</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> redis</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"># HTTP 验证（重启 Apache 后调用依赖 Redis 的接口，见下方「部署验证清单」）</span></span></code></pre></div><h2 id="php-ini-关键配置" tabindex="-1">php.ini 关键配置 <a class="header-anchor" href="#php-ini-关键配置" aria-label="Permalink to "php.ini 关键配置""></a></h2><p><code>$PHP_HOME\\php.ini</code> 中与本项目相关的关键配置：</p><table tabindex="0"><thead><tr><th>配置项</th><th>建议值</th><th>说明</th></tr></thead><tbody><tr><td><code>extension</code> 系列</td><td>按需启用</td><td>项目必需：<code>pdo_mysql</code>、<code>mbstring</code>、<code>gd</code>、<code>bcmath</code>、<code>zip</code>、<code>redis</code>、<code>openssl</code>、<code>fileinfo</code>、<code>curl</code>；跨库迁移目标为 PostgreSQL 时另启用 <code>pdo_pgsql</code></td></tr><tr><td><code>memory_limit</code></td><td><code>256M</code></td><td>Excel 导出等大内存场景</td></tr><tr><td><code>max_execution_time</code></td><td><code>60</code></td><td>导入导出超时上限</td></tr><tr><td><code>upload_max_filesize</code> / <code>post_max_size</code></td><td><code>50M</code></td><td>与 <code>.env</code> 中 <code>FILE_MAX_SIZE</code> 配合（业务限制更小）</td></tr><tr><td><code>date.timezone</code></td><td><code>Asia/Shanghai</code></td><td>与应用时区一致</td></tr><tr><td><code>opcache.enable</code></td><td><code>1</code></td><td>本地开发可保持 <code>opcache.validate_timestamps=1</code>，改代码即时生效</td></tr></tbody></table><p>修改后重启 Apache 生效。</p><h2 id="Redis-密码配置" tabindex="-1">Redis 密码配置 <a class="header-anchor" href="#Redis-密码配置" aria-label="Permalink to "Redis 密码配置""></a></h2><h3 id="状态确认" tabindex="-1">状态确认 <a class="header-anchor" href="#状态确认" aria-label="Permalink to "状态确认""></a></h3><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span style="--shiki-dark:#62E884;--shiki-light:#59873A;">tasklist</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> //FI</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;"> "</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;">IMAGENAME eq redis-server.exe</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;">"</span><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"> # 进程</span></span>
|
||
<span class="line"><span style="--shiki-dark:#62E884;--shiki-light:#59873A;">netstat</span><span style="--shiki-dark:#BF9EEE;--shiki-light:#A65E2B;"> -an</span><span style="--shiki-dark:#F286C4;--shiki-light:#AB5959;"> |</span><span style="--shiki-dark:#62E884;--shiki-light:#59873A;"> findstr</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;"> "</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;">:6379</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;">"</span><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"> # 应看到 127.0.0.1:6379 LISTENING</span></span></code></pre></div><h3 id="设置密码-实际踩坑记录-" tabindex="-1">设置密码（实际踩坑记录） <a class="header-anchor" href="#设置密码-实际踩坑记录-" aria-label="Permalink to "设置密码（实际踩坑记录）""></a></h3><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>Redis 无密码直连可用；一旦 Redis 侧设置了 <code>requirepass</code> 而 <code>.env</code> 未同步（或 <code>.env</code> 配了 <code>REDIS_PASSWORD</code> 而 Redis 侧没设密码），Laravel 所有 Redis 操作（验证码、JWT 会话、限流）会全部失败。验证码接口此时返回「缓存服务(Redis)连接失败，请检查 Redis 配置（地址、端口、密码）后重试」，真实错误（如 <code>ERR AUTH ...</code>）记录在日志 <code>验证码写入 Redis 失败</code> 中。</p></div><p>处理步骤（缺一不可）：</p><ol><li>Redis 服务端设置密码（<code>redis.conf</code> 的 <code>requirepass</code> 或 <code>CONFIG SET requirepass</code>）；</li><li><code>.env</code> 同步配置：</li></ol><div class="language-ini vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ini</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;">REDIS_CLIENT</span><span style="--shiki-dark:#F286C4;--shiki-light:#999999;">=</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">phpredis</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;">REDIS_HOST</span><span style="--shiki-dark:#F286C4;--shiki-light:#999999;">=</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">127.0.0.1</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;">REDIS_PASSWORD</span><span style="--shiki-dark:#F286C4;--shiki-light:#999999;">=</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">你的密码 ← 原为 null，必须改</span></span>
|
||
<span class="line"><span style="--shiki-dark:#F286C4;--shiki-light:#1E754F;">REDIS_PORT</span><span style="--shiki-dark:#F286C4;--shiki-light:#999999;">=</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">6379</span></span></code></pre></div><ol start="3"><li>清除配置缓存并重启 Apache：</li></ol><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span style="--shiki-dark:#BF9EEE;--shiki-light:#B07D48;">$PHP_HOME</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\p</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">hp.exe artisan config:clear</span></span></code></pre></div><h3 id="单独验证-Redis-连通-绕开业务代码-" tabindex="-1">单独验证 Redis 连通（绕开业务代码） <a class="header-anchor" href="#单独验证-Redis-连通-绕开业务代码-" aria-label="Permalink to "单独验证 Redis 连通（绕开业务代码）""></a></h3><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span style="--shiki-dark:#BF9EEE;--shiki-light:#B07D48;">$PHP_HOME</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\p</span><span style="--shiki-dark:#F6F6F4;--shiki-light:#393A34;">hp.exe artisan tinker </span><span style="--shiki-dark:#BF9EEE;--shiki-light:#B07D48;">--execute</span><span style="--shiki-dark:#F286C4;--shiki-light:#999999;">=</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;">"</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;">try { \\Illuminate\\Support\\Facades\\Redis::setex('test:key', 10, 'ok'); echo 'OK: '.\\Illuminate\\Support\\Facades\\Redis::get('test:key'); } catch (\\Throwable </span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\$</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;">e) { echo get_class(</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\$</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;">e).': '.</span><span style="--shiki-dark:#F286C4;--shiki-light:#A65E2B;">\\$</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;">e->getMessage(); }</span><span style="--shiki-dark:#DEE492;--shiki-light:#B5695977;">"</span></span>
|
||
<span class="line"><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"># 输出 OK: ok 即连接正常（测试键 10 秒自动过期）</span></span></code></pre></div><h2 id="部署验证清单" tabindex="-1">部署验证清单 <a class="header-anchor" href="#部署验证清单" aria-label="Permalink to "部署验证清单""></a></h2><p>按顺序全部通过即环境就绪：</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes dracula-soft vitesse-light vp-code" tabindex="0"><code><span class="line"><span>□ $PHP_HOME\\php.exe -v → PHP 8.3.x (ts)</span></span>
|
||
<span class="line"><span>□ $PHP_HOME\\php.exe -m | findstr redis → redis</span></span>
|
||
<span class="line"><span>□ httpd.exe -t → Syntax OK</span></span>
|
||
<span class="line"><span>□ tasklist 查看 redis-server.exe → 进程存在，6379 LISTENING</span></span>
|
||
<span class="line"><span>□ curl http://admin.laravel13.elevue/api/captcha</span></span>
|
||
<span class="line"><span> → {"code":0,"ok":true,"msg":"操作成功","data":{...}}</span></span>
|
||
<span class="line"><span>□ curl -X POST http://admin.laravel13.elevue/api/login</span></span>
|
||
<span class="line"><span> → {"code":1,"ok":false,"msg":"参数验证失败","data":{...}} （路由已通）</span></span></code></pre></div><p>验证码接口返回 <code>code=0</code> 的 JSON 即部署成功——它同时验证了 Apache 重写、PHP 8.3、Redis 连通三条链路。</p><h2 id="常见问题" tabindex="-1">常见问题 <a class="header-anchor" href="#常见问题" aria-label="Permalink to "常见问题""></a></h2><table tabindex="0"><thead><tr><th>症状</th><th>原因</th><th>处理</th></tr></thead><tbody><tr><td><code>/</code> 正常，<code>/api/*</code> 返回 Apache 原生 HTML 404</td><td>vhost 缺 <code><Directory></code> 块，<code>.htaccess</code> 被忽略</td><td>补 <code>AllowOverride All</code> 块，<code>httpd -t</code> 后重启 Apache</td></tr><tr><td><code>Class "Redis" not found</code></td><td>PHP 缺 redis 扩展</td><td>装 <code>php_redis.dll</code> + <code>php.ini</code> 加 <code>extension=redis</code></td></tr><tr><td>验证码接口返回「缓存服务(Redis)连接失败…」</td><td>Redis 密码不匹配或服务未启</td><td>日志搜 <code>验证码写入 Redis 失败</code> 看真实错误；<code>.env</code> 配 <code>REDIS_PASSWORD</code>，tinker 单测 Redis 连通</td></tr><tr><td>artisan/pint 报 requires PHP >= 8.3</td><td>shell PATH 的 php 是旧版</td><td>用 <code>$PHP_HOME\\php.exe</code> 完整路径调用</td></tr><tr><td><code>httpd -k restart</code> 报 No installed service</td><td>Apache 未注册 Windows 服务</td><td><code>taskkill</code> 后重新启动 <code>httpd.exe</code></td></tr><tr><td>改了配置 / 扩展不生效</td><td>mod_php 常驻不热加载</td><td>必须重启 Apache</td></tr></tbody></table><h2 id="相关页面" tabindex="-1">相关页面 <a class="header-anchor" href="#相关页面" aria-label="Permalink to "相关页面""></a></h2><ul><li><a href="/zh/quickstart/environment.html">2.1 开发环境准备</a> — 版本要求总览</li><li><a href="/zh/quickstart/backend-start.html">2.3 后端服务启动</a> — 安装依赖、初始化项目</li><li><a href="/zh/quickstart/env-vars.html">2.6 环境变量配置</a> — <code>.env</code> 全部配置项说明</li><li><a href="/zh/quickstart/faq.html">2.9 常见问题 FAQ</a> — 更多启动期问题</li></ul>`,71)])])}const g=a(n,[["render",l]]);export{c as __pageData,g as default};
|