本文详解 ci4 中 auth 过滤器因未正确声明 exception 命名空间导致 json 响应崩溃的问题，提供修复方案、最佳实践与安全建议。
本文详解 ci4 中 auth 过滤器因未正确声明 exception 命名空间导致 json 响应崩溃的问题，提供修复方案、最佳实践与安全建议。
在 CodeIgniter 4 中实现 JWT 认证过滤器时，一个常见却极易被忽视的陷阱是：未正确处理 PHP 异常的命名空间，这会导致非法 Token 触发底层 JSON 格式化失败（Failed to parse json string），最终返回 500 错误页面而非预期的 JSON 错误响应。
根本原因在于：当文件声明了 namespace App\Filters; 后，所有未加前缀的类名（如 Exception）都会被自动解析为当前命名空间下的类（即 \App\Filters\Exception），而该类并不存在。此时 catch (Exception $ex) 实际捕获失败，异常穿透至框架全局异常处理器，触发 JSONFormatter::format() 对非 UTF-8 安全的错误堆栈进行 JSON 编码——而堆栈中可能含二进制或乱码字符，引发 Malformed UTF-8 characters 错误。
✅ 正确做法是显式使用 PHP 内置异常类的完整命名空间：
<?php
namespace App\Filters;
use CodeIgniter\Filters\FilterInterface;
use CodeIgniter\HTTP\RequestInterface;
use CodeIgniter\HTTP\ResponseInterface;
use Firebase\JWT\JWT;
use Firebase\JWT\Key;
use Exception; // ✅ 显式导入全局 Exception 类
class Auth implements FilterInterface
{
public function before(RequestInterface $request, $arguments = null)
{
$key = getenv('JWT_SECRET') ?: 'your-secret-key';
$header = $request->getServer('HTTP_AUTHORIZATION');
$token = null;
if (!empty($header) && preg_match('/^Bearer\s+(.+)$/i', $header, $matches)) {
$token = $matches[1];
}
if (empty($token)) {
return $this->jsonResponse(401, 'Token required.');
}
try {
JWT::decode($token, new Key($key, 'HS256'));
return; // ✅ 允许请求继续
} catch (Exception $e) { // ✅ 现在能正确捕获所有 JWT 相关异常
return $this->jsonResponse(401, 'Access denied.');
}
}
private function jsonResponse(int $status, string $message): ResponseInterface
{
$response = [
'status' => $status,
'error' => true,
'message' => $message,
'data' => []
];
return service('response')
->setStatusCode($status)
->setJSON($response);
}
public function after(RequestInterface $request, ResponseInterface $response, $arguments = null)
{
// 可选：后置逻辑（如日志记录）
}
}? 关键改进点说明：
- 显式 use Exception;：确保捕获所有标准异常（包括 DomainException、InvalidArgumentException 等 JWT 库抛出的异常）；
- 避免 echo + exit()：改用 CI4 原生 ResponseInterface 返回结构化响应，保证 Content-Type、状态码和格式一致性；
- 增强 Token 提取健壮性：使用正则匹配 Bearer <token>，防止空格/大小写问题；
- 封装响应逻辑：复用 jsonResponse() 方法提升可维护性，并支持后续扩展（如添加 trace ID、错误码分类等）；
- 环境变量兜底：getenv('JWT_SECRET') ?: 'fallback' 避免开发环境因缺失配置直接报错。
⚠️ 注意事项：
- 不要仅捕获 Firebase\JWT\BeforeValidException 等特定异常——JWT 库多数异常继承自 Exception，统一捕获更安全；
- 生产环境务必关闭 display_errors，并启用 CI_ENVIRONMENT = production，防止敏感堆栈泄露；
- 建议配合 try-catch 外层增加日志记录（如 log_message('error', $e->getMessage())），便于审计非法 Token 攻击行为。
通过以上修正，非法 Token 将稳定返回标准 JSON 错误响应（如 {"status":401,"error":true,"message":"Access denied.","data":[]}），彻底规避 FormatException 和 500 崩溃，显著提升 API 的健壮性与可观测性。
