跳到主要内容

常见问题与修复

最常见问题及其解决方案的综合指南。

安装问题​

安装后页面空白​

原因： 通常是文件权限问题。

修复：

# 检查 Laravel 日志
tail -50 storage/logs/laravel.log

# 修复权限
sudo chmod -R 775 storage bootstrap/cache
sudo chown -R www-data:www-data storage bootstrap/cache

"Class Not Found"（找不到类）错误​

原因： Composer 依赖项未安装或自动加载器未生成。

修复：

composer install --no-dev --optimize-autoloader
php artisan config:clear

安装程序显示"已安装"​

原因： storage/installed.lock 文件存在。

修复： 如需重新运行安装程序：

rm storage/installed.lock

然后再次访问 /install。

CSS/JS 无法加载（页面无样式）​

原因： 存储软链接缺失或资源路径问题。

修复：

php artisan storage:link
php artisan config:clear
php artisan view:clear

同时检查 .env 中的 APP_URL 是否与您的实际域名一致（包含 https://）。

数据库问题​

"SQLSTATE[HY000] [2002] Connection Refused"（数据库连接被拒绝）​

原因： MySQL 未运行或主机地址错误。

修复：

  • 检查 MySQL 是否运行：sudo systemctl status mysql
  • 在 .env 中尝试使用 127.0.0.1 代替 localhost
  • 验证端口（默认：3306）

"SQLSTATE[HY000] [1045] Access Denied"（访问被拒绝）​

原因： 数据库凭据错误。

修复：

  • 验证 .env 中的用户名/密码
  • 测试连接：mysql -u your_user -p your_database
  • 重新授权：
GRANT ALL PRIVILEGES ON feedbackpulse.* TO 'your_user'@'localhost';
FLUSH PRIVILEGES;

Emoji 显示为 ????​

原因： 数据库字符集为 utf8 而非 utf8mb4。

修复：

ALTER DATABASE feedbackpulse CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Web 服务器问题​

所有路由返回 404​

Apache 修复：

sudo a2enmod rewrite
sudo systemctl restart apache2

确保虚拟主机中设置了 AllowOverride All。

Nginx 修复： 确保服务器块中包含：

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

502 Bad Gateway（Nginx）​

原因： PHP-FPM 未运行或 socket 路径错误。

修复：

sudo systemctl restart php8.4-fpm
# 检查 socket 路径
ls /var/run/php/php8.4-fpm.sock

413 Request Entity Too Large（请求体过大）​

原因： 上传大小限制过低。

Nginx 修复：

client_max_body_size 20M;

PHP 修复：

upload_max_filesize = 20M
post_max_size = 25M

认证问题​

"CSRF Token Mismatch"（CSRF Token 不匹配，419 错误）​

原因： Session 已过期或 Cookie 问题。

修复：

  • 清除浏览器 Cookie 后重试
  • 检查 .env 中的 SESSION_DOMAIN（子域名时设置为 .yourdomain.com）
  • 仅在使用 HTTPS 时将 SESSION_SECURE_COOKIE=true

密码重置后无法登录​

原因： 浏览器缓存了旧 Session。

修复： 清除浏览器 Cookie 或使用无痕模式。

社交登录返回错误​

原因： 回调 URL 不匹配。

修复： 确保 Google/GitHub 控制台中的回调 URL 与以下地址完全一致：

  • Google：https://yourdomain.com/auth/google/callback
  • GitHub：https://yourdomain.com/auth/github/callback

支付问题​

详细的支付排查请参阅支付网关问题。

邮件问题​

详细的邮件排查请参阅邮件无法发送。

性能问题​

优化建议请参阅性能优化。

缓存问题​

有疑问时，清除所有缓存：

php artisan optimize:clear

此命令清除以下内容：

  • 配置缓存
  • 路由缓存
  • 视图缓存
  • 应用缓存
  • 编译类缓存

调试模式（临时）​

查看详细错误信息：

  1. 编辑 .env：
APP_DEBUG=true
LOG_LEVEL=debug
  1. 重现错误
  2. 检查错误页面或 storage/logs/laravel.log
  3. 完成后立即设置 APP_DEBUG=false！
注意

切勿在生产环境中保留 APP_DEBUG=true。 这会暴露敏感信息。

获取帮助​

如果以上方法均无法解决问题：

  1. 检查 storage/logs/laravel.log 获取完整错误追踪
  2. 检查 Web 服务器错误日志（/var/log/nginx/error.log 或 /var/log/apache2/error.log）
  3. 在 CodeCanyon 商品评论中搜索类似问题
  4. 提交包含以下信息的支持工单：
    • 错误消息（来自日志）
    • PHP 版本（php -v）
    • Laravel 版本
    • 服务器详情（操作系统、Web 服务器、MySQL 版本）
    • 复现步骤