2 lines
6.8 KiB
JavaScript
2 lines
6.8 KiB
JavaScript
import{_ as d,o as e,c as o,a2 as a}from"./chunks/framework.B-QBKwc1.js";const b=JSON.parse('{"title":"常见问题汇总","description":"本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。","frontmatter":{},"headers":[],"relativePath":"zh/appendix/faq.md","filePath":"zh/appendix/faq.md"}'),r={name:"zh/appendix/faq.md"};function c(l,t,i,n,s,p){return e(),o("div",null,[...t[0]||(t[0]=[a('<h1 id="A-常见问题汇总" tabindex="-1">A. 常见问题汇总 <a class="header-anchor" href="#A-常见问题汇总" aria-label="Permalink to "A. 常见问题汇总""></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><table tabindex="0"><thead><tr><th>问题</th><th>解决方案</th></tr></thead><tbody><tr><td>PHP 版本低于 8.3</td><td>升级到 PHP 8.3+（Laravel 13 要求），项目使用了 8.3 的语言特性</td></tr><tr><td>缺少 pdo_mysql 扩展</td><td><code>apt install php8.3-mysql</code> 或 <code>dnf install php-mysqlnd</code></td></tr><tr><td><code>could not find driver</code>（<code>db:migrate</code> 迁到 PostgreSQL）</td><td>php.ini 扩展区启用 <code>extension=pdo_pgsql</code>（Windows 自带 <code>php_pdo_pgsql.dll</code> + <code>libpq.dll</code>，取消注释即可；Linux <code>apt install php8.3-pgsql</code>），CLI 重读 php.ini 无需重启</td></tr><tr><td>缺少 gd 扩展</td><td><code>apt install php8.3-gd</code> 或 <code>dnf install php-gd</code></td></tr><tr><td>缺少 redis 扩展</td><td><code>apt install php8.3-redis</code> 或 <code>pecl install redis</code>（<strong>必需</strong>：缓存/会话/队列/JWT 均依赖）</td></tr><tr><td>Redis 未安装</td><td>安装 Redis 6.0+ 并配置密码（本项目 <code>.env.example</code> 默认全部 Redis 驱动，不建议改 file）</td></tr><tr><td>Composer 下载慢</td><td><code>composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/</code></td></tr><tr><td>Oracle pdo_oci 加载失败（Windows）</td><td>安装 Oracle Instant Client 19c + VC++ 2015-2022 Redistributable，php.ini 启用 <code>extension=pdo_oci</code>，配置系统 PATH 后重启 Apache</td></tr><tr><td>命令行有 pdo_oci，浏览器 phpinfo 没有</td><td>Apache 服务启动时 PATH 未刷新，完全停止再启动 Apache 即可</td></tr><tr><td>Oracle Instant Client 路径含中文/空格导致加载失败</td><td>解压到 <code>C:\\oracle\\instantclient_19_20</code> 等固定路径，避免空格与中文</td></tr></tbody></table><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><code>php artisan serve --port=8080</code></td></tr><tr><td>数据库连接失败</td><td>检查 <code>.env</code> 中的数据库配置（注意 <code>DB_PREFIX=laravel_</code> 与 SQL 脚本一致）</td></tr><tr><td>表不存在</td><td>本项目无 migration 建表，导入 <code>document/mysql/*.sql</code>（见 <a href="/zh/quickstart/database-init.html">2.5 数据库初始化</a>）</td></tr><tr><td>401 未授权</td><td>检查请求头是否携带 <code>Authorization: Bearer <token></code>，确认 <code>JWT_SECRET</code> 配置（缺失/过短会 fail-close）</td></tr><tr><td>403 禁止访问</td><td>检查用户权限配置，确认角色已分配菜单</td></tr><tr><td>502 Bad Gateway</td><td>检查 PHP-FPM 是否启动：<code>systemctl status php8.3-fpm</code></td></tr><tr><td>登录失败/缓存不生效</td><td>检查 Redis 是否运行、<code>REDIS_*</code> 配置是否正确（见 <a href="/zh/deploy/troubleshooting.html">11.10 故障排查手册</a>）</td></tr></tbody></table><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>检查数据是否重复，确认 <code>uniqueFields</code> 配置</td></tr><tr><td>枚举显示名为空</td><td>检查字典配置，确认 <code>serializeMaps</code> 正确、字典编码已创建</td></tr><tr><td>文件上传失败</td><td>检查 <code>FILE_UPLOAD_DIR</code> / <code>FILE_MAX_SIZE</code> 配置和 <code>public/uploads/</code> 目录权限</td></tr><tr><td>导入失败</td><td>检查 Excel 表头是否与 <code>headerMap</code> 一致</td></tr><tr><td>排序不生效</td><td>检查 <code>pageOrderBy</code> 配置，或前端 <code>orderField</code> 是否在白名单（<code>pageOrderBy</code> ∪ <code>orderFieldAllow</code>）内</td></tr></tbody></table><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>pnpm install 失败</td><td><code>rm -rf node_modules && pnpm install --force</code>（锁文件 <code>pnpm-lock.yaml</code> 保留）</td></tr><tr><td>API 404</td><td>检查后端路由注册和 Vite 代理 / Nginx <code>proxy_pass</code> 配置</td></tr><tr><td>菜单不显示</td><td>检查菜单配置、组件路径、角色权限，重新登录刷新动态菜单</td></tr><tr><td>白屏</td><td>打开 F12 控制台查看错误</td></tr><tr><td>Token 频繁过期</td><td>检查 <code>JWT_ACCESS_TTL</code> 配置（默认 7200 秒），或使用 <code>refresh</code> 刷新令牌</td></tr></tbody></table><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>检查 crontab 配置：<code>crontab -l</code>；手动执行 <code>php artisan job:run</code> 验证</td></tr><tr><td>任务重复执行</td><td>检查是否有多个 <code>job:run</code> cron 或 <code>job:daemon</code> 守护进程在运行</td></tr><tr><td>任务执行超时</td><td>检查 PHP <code>max_execution_time</code> 配置</td></tr><tr><td>内部任务处理器不存在</td><td><code>url</code> 字段按 <code>App\\Task\\{名称}Task</code> 映射，确认类名与 <code>run()</code> 方法存在（见 <a href="/zh/modules/job.html">6.11 定时任务</a>）</td></tr></tbody></table>',12)])])}const m=d(r,[["render",c]]);export{b as __pageData,m as default};
|