SunAdmin 开发文档

主题

❓ 常见问题 ​

安装与部署 ​

如何重新运行安装向导？ ​

删除项目根目录下的 install.lock 文件，然后重新访问 /install：

bash
rm install.lock

本地上传文件无法通过 /storage/... 访问？ ​

执行软链接命令：

bash
php artisan storage:link

如果初始化后更改了项目路径，也需要重新执行此命令。

安装向导报数据库连接失败？ ​

确认 .env 中的数据库配置正确，且数据库服务已启动。如果使用 Docker，确认容器端口已映射到宿主机。

Nginx 相关 ​

接口返回 404 或 403？ ​

检查 Nginx 配置：

  1. root 是否指向项目的 public 目录。
  2. 是否配置了 try_files $uri $uri/ /index.php?$query_string;。
  3. PHP-FPM 的 fastcgi_pass 路径是否正确。

登录后接口仍然返回"未登录"？ ​

Nginx 需要透传 Authorization 请求头：

nginx
fastcgi_param HTTP_AUTHORIZATION $http_authorization;

详见 部署发布。

Admin 前端请求报 CSRF 校验失败？ ​

Nginx 需要透传 X-XSRF-Token 请求头：

nginx
fastcgi_param HTTP_X_XSRF_TOKEN $http_x_xsrf_token;

前端开发 ​

Admin 开发服务启动后无法访问接口？ ​

确认后端服务已启动，且 frontend/admin/.env.development 中的 VITE_APP_BASE_URL 指向后端地址。Admin 默认开发端口为 8000，接口前缀为 adminapi。

uni-app 安装依赖报版本不兼容？ ​

uni-app 项目需要使用指定 npm 版本安装依赖：

bash
npx npm@11.13.0 install

小程序真机请求失败？ ​

小程序必须使用 HTTPS 域名，且域名需在小程序后台"开发管理 / 服务器域名"中配置。确认 VITE_APP_BASE_URL 填写的是完整域名。

后端开发 ​

模块安装后接口返回"模块未启用"？ ​

确认模块的 manifest 配置正确，且已在后台应用中心启用。模块未启用时，其路由不会注册。

配置修改后不生效？ ​

  • 开发环境：重启 php artisan serve。
  • 生产环境：清理配置缓存 php artisan config:clear 或重新缓存 php artisan config:cache。

数据库迁移报错？ ​

如果当前环境被识别为生产环境，需要加 --force 参数：

bash
php artisan migrate --force

错误码相关 ​

接口返回 code: 10002 是什么？ ​

登录失效或 Token 过期，前端会自动跳转登录页。详见 错误码参考。

接口返回 code: 10004 是什么？ ​

当前用户无权限访问该接口，需要在后台为对应角色分配权限。详见 错误码参考。