2 lines
19 KiB
JavaScript
2 lines
19 KiB
JavaScript
import{_ as s,o as e,c as i,a2 as t}from"./chunks/framework.B-QBKwc1.js";const k=JSON.parse('{"title":"常见问题 FAQ","description":"本页收录环境搭建与首次运行阶段的常见问题，按环境、数据库与启动等场景分类，快速入门受阻时优先按症状查阅。","frontmatter":{},"headers":[],"relativePath":"zh/quickstart/faq.md","filePath":"zh/quickstart/faq.md"}'),o={name:"zh/quickstart/faq.md"};function l(h,a,n,d,r,p){return e(),i("div",null,[...a[0]||(a[0]=[t('<h1 id="_2-9-常见问题-FAQ" tabindex="-1">2.9 常见问题 FAQ <a class="header-anchor" href="#_2-9-常见问题-FAQ" aria-label="Permalink to "2.9 常见问题 FAQ""></a></h1><div class="tip custom-block"><p class="custom-block-title">概述</p><p>本页收录环境搭建与首次运行阶段的常见问题，按环境、数据库与启动等场景分类，快速入门受阻时优先按症状查阅。</p></div><h2 id="环境相关" tabindex="-1">环境相关 <a class="header-anchor" href="#环境相关" aria-label="Permalink to "环境相关""></a></h2><h3 id="Q-PHP-版本低于-8-3-能运行吗-" tabindex="-1">Q: PHP 版本低于 8.3 能运行吗？ <a class="header-anchor" href="#Q-PHP-版本低于-8-3-能运行吗-" aria-label="Permalink to "Q: PHP 版本低于 8.3 能运行吗？""></a></h3><p>A: 不能。项目基于 Laravel 13（composer.json 要求 <code>php ^8.3</code>），必须使用 PHP 8.3+。执行 <code>composer install</code> 时 Composer 会直接校验版本并报错。</p><h3 id="Q-缺少-PHP-扩展怎么办-" tabindex="-1">Q: 缺少 PHP 扩展怎么办？ <a class="header-anchor" href="#Q-缺少-PHP-扩展怎么办-" aria-label="Permalink to "Q: 缺少 PHP 扩展怎么办？""></a></h3><p>A: 运行 <code>php -m</code> 检查已安装的扩展。缺少的扩展参考 <a href="/zh/quickstart/environment.html">2.1 开发环境准备</a> 安装。最常见的是缺少 <code>pdo_mysql</code>、<code>gd</code> 和 <strong><code>redis</code></strong>——<code>redis</code> 扩展缺失时报 <code>Class "Redis" not found</code>，验证码、登录直接不可用。</p><h3 id="Q-Composer-安装很慢怎么办-" tabindex="-1">Q: Composer 安装很慢怎么办？ <a class="header-anchor" href="#Q-Composer-安装很慢怎么办-" aria-label="Permalink to "Q: Composer 安装很慢怎么办？""></a></h3><p>A: 配置中国镜像：</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:#7B7F8B;--shiki-light:#A0ADA0;"># 配置阿里云 Composer 镜像（加速依赖下载）</span></span>\n<span class="line"><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"># -g → 修改全局配置（所有项目生效）</span></span>\n<span class="line"><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"># repo.packagist → 设置 Packagist 仓库镜像地址</span></span>\n<span class="line"><span style="--shiki-dark:#62E884;--shiki-light:#59873A;">composer</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> config</span><span style="--shiki-dark:#BF9EEE;--shiki-light:#A65E2B;"> -g</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> repo.packagist</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> composer</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> https://mirrors.aliyun.com/composer/</span></span></code></pre></div><h3 id="Q-Redis-不安装可以吗-" tabindex="-1">Q: Redis 不安装可以吗？ <a class="header-anchor" href="#Q-Redis-不安装可以吗-" aria-label="Permalink to "Q: Redis 不安装可以吗？""></a></h3><p>A: <strong>不可以。</strong> 本项目强依赖 Redis：验证码、JWT 双令牌会话、权限缓存、字典缓存、会话/队列驱动均依赖它。Redis 相关问题（扩展安装、密码同步）见 <a href="/zh/quickstart/environment.html">2.1 开发环境准备</a> 与 <a href="/zh/quickstart/laragon.html">2.2 Laragon 环境搭建</a>。</p><h3 id="Q-shell-里执行-php-artisan-报版本过低-找不到类-" tabindex="-1">Q: shell 里执行 php artisan 报版本过低 / 找不到类？ <a class="header-anchor" href="#Q-shell-里执行-php-artisan-报版本过低-找不到类-" aria-label="Permalink to "Q: shell 里执行 php artisan 报版本过低 / 找不到类？""></a></h3><p>A: PATH 中的 <code>php</code> 可能是旧版本（Laragon 默认 PATH 常指向低版本 PHP）。使用 8.3 的完整路径调用：</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>\n<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><h2 id="启动相关" tabindex="-1">启动相关 <a class="header-anchor" href="#启动相关" aria-label="Permalink to "启动相关""></a></h2><h3 id="Q-php-artisan-serve-报-Address-already-in-use-" tabindex="-1">Q: <code>php artisan serve</code> 报 "Address already in use" <a class="header-anchor" href="#Q-php-artisan-serve-报-Address-already-in-use-" aria-label="Permalink to "Q: `php artisan serve` 报 "Address already in use"""></a></h3><p>A: 端口被占用，更换端口：</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:#7B7F8B;--shiki-light:#A0ADA0;"># --port → 指定监听端口（默认 8000）</span></span>\n<span class="line"><span style="--shiki-dark:#62E884;--shiki-light:#59873A;">php</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> artisan</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> serve</span><span style="--shiki-dark:#BF9EEE;--shiki-light:#A65E2B;"> --port=8080</span></span></code></pre></div><h3 id="Q-应用拒绝启动-报-JWT-SECRET-错误-" tabindex="-1">Q: 应用拒绝启动，报 JWT_SECRET 错误？ <a class="header-anchor" href="#Q-应用拒绝启动-报-JWT-SECRET-错误-" aria-label="Permalink to "Q: 应用拒绝启动，报 JWT_SECRET 错误？""></a></h3><p>A: <code>.env</code> 中 <code>JWT_SECRET</code> 为空或不足 32 字符——应用启动时执行 fail-close 校验（不满足直接抛异常）。生成强随机密钥后重启：</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:#62E884;--shiki-light:#59873A;">openssl</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> rand</span><span style="--shiki-dark:#BF9EEE;--shiki-light:#A65E2B;"> -base64</span><span style="--shiki-dark:#BF9EEE;--shiki-light:#2F798A;"> 32</span><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"> # 或 php -r "echo bin2hex(random_bytes(32));"</span></span></code></pre></div><h3 id="Q-数据库连接失败-Connection-refused-或表不存在-" tabindex="-1">Q: 数据库连接失败 "Connection refused" 或表不存在？ <a class="header-anchor" href="#Q-数据库连接失败-Connection-refused-或表不存在-" aria-label="Permalink to "Q: 数据库连接失败 "Connection refused" 或表不存在？""></a></h3><p>A: 检查以下几点：</p><ol><li>MySQL 服务是否启动：<code>systemctl status mysql</code></li><li><code>.env</code> 中的 <code>DB_*</code> 配置是否正确（<code>DB_HOST</code>、<code>DB_PORT</code>、<code>DB_USERNAME</code>、<code>DB_PASSWORD</code>、<code>DB_DATABASE</code>）</li><li>数据库是否已创建并导入 <code>document/mysql/rxthinkcmf.laravel13.elevue.sql</code>（本项目 migrations 为空，<strong>不会自动建表</strong>）</li><li><code>DB_PREFIX</code> 是否为 <code>laravel_</code>（漏配会报 <code>Table 'xxx.users' doesn't exist</code>）</li><li>原生测试连接：<code>mysql -h 127.0.0.1 -P 3306 -u root -p -e "SELECT 1;"</code></li></ol><h3 id="Q-登录返回-401" tabindex="-1">Q: 登录返回 401 <a class="header-anchor" href="#Q-登录返回-401" aria-label="Permalink to "Q: 登录返回 401""></a></h3><p>A: 可能原因：</p><ol><li>Token 过期 → 重新登录（access_token 默认 2 小时，refresh_token 7 天）</li><li>请求头格式错误 → 确保是 <code>Authorization: Bearer <token></code></li><li><code>JWT_SECRET</code> 变更 → 旧令牌全部失效，重新登录即可</li><li>Redis 中会话被清除（如重启 Redis、执行 <code>FLUSHDB</code>）→ 重新登录</li></ol><h2 id="前端相关" tabindex="-1">前端相关 <a class="header-anchor" href="#前端相关" aria-label="Permalink to "前端相关""></a></h2><h3 id="Q-pnpm-install-报错" tabindex="-1">Q: <code>pnpm install</code> 报错 <a class="header-anchor" href="#Q-pnpm-install-报错" aria-label="Permalink to "Q: `pnpm install` 报错""></a></h3><p>A: 清除缓存重新安装：</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:#7B7F8B;--shiki-light:#A0ADA0;"># 删除依赖目录和锁文件，重新安装</span></span>\n<span class="line"><span style="--shiki-dark:#62E884;--shiki-light:#59873A;">rm</span><span style="--shiki-dark:#BF9EEE;--shiki-light:#A65E2B;"> -rf</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> node_modules</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> pnpm-lock.yaml</span><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"> # 删除旧的依赖和锁文件</span></span>\n<span class="line"><span style="--shiki-dark:#62E884;--shiki-light:#59873A;">pnpm</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> install</span><span style="--shiki-dark:#7B7F8B;--shiki-light:#A0ADA0;"> # 重新安装所有依赖</span></span></code></pre></div><h3 id="Q-前端请求后端-404" tabindex="-1">Q: 前端请求后端 404 <a class="header-anchor" href="#Q-前端请求后端-404" aria-label="Permalink to "Q: 前端请求后端 404""></a></h3><p>A: 检查以下几点：</p><ol><li>后端服务是否启动（<code>curl http://admin.laravel13.elevue/api/captcha</code> 验证）</li><li>Vite 代理配置是否正确（<code>vite.config.ts</code> 中的 <code>target</code>，改完重启 <code>pnpm dev</code>）</li><li>API 路径是否正确（应以 <code>/api</code> 开头）</li></ol><h3 id="Q-页面白屏" tabindex="-1">Q: 页面白屏 <a class="header-anchor" href="#Q-页面白屏" aria-label="Permalink to "Q: 页面白屏""></a></h3><p>A: 打开浏览器控制台（F12）查看错误信息，常见原因：</p><ol><li>JS 加载失败 → 检查网络请求</li><li>路由配置错误 → 检查后端菜单数据（<code>/api/index/getMenus</code> 是否正常返回）</li><li>Token 过期 → 重新登录</li></ol><h2 id="数据库初始化相关" tabindex="-1">数据库初始化相关 <a class="header-anchor" href="#数据库初始化相关" aria-label="Permalink to "数据库初始化相关""></a></h2><h3 id="Q-composer-setup-php-artisan-migrate-后依然提示表不存在-" tabindex="-1">Q: <code>composer setup</code> / <code>php artisan migrate</code> 后依然提示表不存在？ <a class="header-anchor" href="#Q-composer-setup-php-artisan-migrate-后依然提示表不存在-" aria-label="Permalink to "Q: `composer setup` / `php artisan migrate` 后依然提示表不存在？""></a></h3><p>A: 正常现象。本项目 <code>database/migrations/</code> 为空，<strong>建表以 SQL 脚本为准</strong>，<code>migrate</code> 只初始化迁移记录表。请手动导入：</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:#62E884;--shiki-light:#59873A;">mysql</span><span style="--shiki-dark:#BF9EEE;--shiki-light:#A65E2B;"> -uroot</span><span style="--shiki-dark:#BF9EEE;--shiki-light:#A65E2B;"> -proot</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> rxthinkcmf.laravel13.elevue</span><span style="--shiki-dark:#F286C4;--shiki-light:#AB5959;"> <</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> document/mysql/rxthinkcmf.laravel13.elevue.sql</span></span></code></pre></div><p>详见 <a href="/zh/quickstart/database-init.html">2.5 数据库初始化</a>。</p><h3 id="Q-导入-SQL-很慢或中断-" tabindex="-1">Q: 导入 SQL 很慢或中断？ <a class="header-anchor" href="#Q-导入-SQL-很慢或中断-" aria-label="Permalink to "Q: 导入 SQL 很慢或中断？""></a></h3><p>A: 脚本约 226MB（含全国行政区划等大数据量表），导入需 1~3 分钟属正常。确保：</p><ol><li>数据库字符集为 <code>utf8mb4</code></li><li>命令行窗口保持打开直到导入完成</li><li>MySQL 的 <code>max_allowed_packet</code> 足够（默认 64MB 一般够用，不足时调大）</li></ol><h2 id="Docker-相关" tabindex="-1">Docker 相关 <a class="header-anchor" href="#Docker-相关" aria-label="Permalink to "Docker 相关""></a></h2><h3 id="Q-Docker-启动后-mysql-一直-unhealthy-" tabindex="-1">Q: Docker 启动后 mysql 一直 unhealthy？ <a class="header-anchor" href="#Q-Docker-启动后-mysql-一直-unhealthy-" aria-label="Permalink to "Q: Docker 启动后 mysql 一直 unhealthy？""></a></h3><p>A: 首次启动需导入约 226MB SQL，健康检查已预留缓冲（1~3 分钟）。查看进度：</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:#62E884;--shiki-light:#59873A;">docker</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> compose</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> logs</span><span style="--shiki-dark:#BF9EEE;--shiki-light:#A65E2B;"> -f</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> mysql</span></span></code></pre></div><p>详见 <a href="/zh/quickstart/docker.html">2.8 Docker 快速体验</a>。</p><h3 id="Q-Docker-启动即退出-日志报-JWT-SECRET-" tabindex="-1">Q: Docker 启动即退出，日志报 JWT_SECRET？ <a class="header-anchor" href="#Q-Docker-启动即退出-日志报-JWT-SECRET-" aria-label="Permalink to "Q: Docker 启动即退出，日志报 JWT_SECRET？""></a></h3><p>A: 容器内读取的 <code>JWT_SECRET</code> 不足 32 字符。在 <code>docker/.env.docker</code> 中生成随机值后重启：</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:#62E884;--shiki-light:#59873A;">openssl</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> rand</span><span style="--shiki-dark:#BF9EEE;--shiki-light:#A65E2B;"> -base64</span><span style="--shiki-dark:#BF9EEE;--shiki-light:#2F798A;"> 32</span></span>\n<span class="line"><span style="--shiki-dark:#62E884;--shiki-light:#59873A;">docker</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> compose</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> restart</span><span style="--shiki-dark:#E7EE98;--shiki-light:#B56959;"> app</span></span></code></pre></div><h3 id="Q-本机-Laragon-与-Docker-端口冲突-" tabindex="-1">Q: 本机 Laragon 与 Docker 端口冲突？ <a class="header-anchor" href="#Q-本机-Laragon-与-Docker-端口冲突-" aria-label="Permalink to "Q: 本机 Laragon 与 Docker 端口冲突？""></a></h3><p>A: 修改 <code>docker/.env.docker</code> 中的宿主机端口（如 <code>MYSQL_PORT=3307</code>、<code>REDIS_PORT=6380</code>），容器内部通过服务名通信不受影响。见 <a href="/zh/quickstart/docker.html">2.8 Docker 快速体验</a> 「端口冲突处理」。</p><h2 id="认证与权限相关" tabindex="-1">认证与权限相关 <a class="header-anchor" href="#认证与权限相关" aria-label="Permalink to "认证与权限相关""></a></h2><h3 id="Q-接口返回-code-403-msg-无访问权限-" tabindex="-1">Q: 接口返回 <code>{"code":403,"msg":"无访问权限"}</code>？ <a class="header-anchor" href="#Q-接口返回-code-403-msg-无访问权限-" aria-label="Permalink to "Q: 接口返回 `{"code":403,"msg":"无访问权限"}`？""></a></h3><p>A: 当前账号角色缺少该接口的权限节点。到「系统管理 → 角色管理」为角色勾选对应菜单/按钮权限（权限码如 <code>sys:user:add</code>），或使用超级管理员账号测试。权限模型见 <a href="/zh/core/rbac.html">5.4 权限管理（RBAC）</a>。</p><h3 id="Q-接口返回-code-401-msg-未授权-请先登录-" tabindex="-1">Q: 接口返回 <code>{"code":401,"msg":"未授权，请先登录"}</code>？ <a class="header-anchor" href="#Q-接口返回-code-401-msg-未授权-请先登录-" aria-label="Permalink to "Q: 接口返回 `{"code":401,"msg":"未授权，请先登录"}`？""></a></h3><p>A: Token 缺失、无效或过期。检查：</p><ol><li>请求头是否携带 <code>Authorization: Bearer <token></code></li><li>access_token 是否过期（默认 2 小时），过期后调 <code>/api/refresh</code> 续签或重新登录</li><li>是否被踢下线 / 改密后全端失效（Redis 会话已清除）</li></ol><h3 id="Q-接口都是-HTTP-200-怎么判断成功失败-" tabindex="-1">Q: 接口都是 HTTP 200，怎么判断成功失败？ <a class="header-anchor" href="#Q-接口都是-HTTP-200-怎么判断成功失败-" aria-label="Permalink to "Q: 接口都是 HTTP 200，怎么判断成功失败？""></a></h3><p>A: 项目约定 HTTP 状态码恒为 200（403 例外），以响应体 <code>code</code> 判断：<code>code=0</code> 成功，其他为失败；<code>code=401</code> 时前端跳转登录。见 <a href="/zh/api-spec/response.html">8.1 统一响应格式</a>。</p>',64)])])}const u=s(o,[["render",l]]);export{k as __pageData,u as default};
|