禁用 Yii 默认 HTML 异常渲染需重写 errorHandler 组件并指定 errorAction 为 API 错误处理动作，使所有异常返回标准 JSON 格式 {code, message, data}，并通过状态码映射表统一转换 HTTP 状态到业务 code。
Yii 框架默认把所有异常渲染成 HTML 页面，API 请求拿到的要么是空响应、要么是混着 <html> 标签的 JSON，根本没法被客户端正常解析。必须绕过 yii\web\ErrorHandler 的 HTML 渲染链，让所有错误走纯 JSON 流程。
怎么禁用 ErrorHandler 的 HTML 渲染？
别指望靠 'responseFormat' => \yii\web\Response::FORMAT_JSON 全局配置——它只管正常返回，不管异常。关键动作是切断 yii\web\ErrorHandler 对 API 请求的接管：
- 在
config/web.php的components里移除或重写'errorHandler' => ['errorAction' => 'site/error'] - 更稳妥的做法：在应用启动早期（比如
bootstrap或beforeAction）判断请求类型：Yii::$app->request->getIsJson() || Yii::$app->request->getIsAjax() - 满足条件时，直接
throw new \yii\web\HttpException(400, 'Bad Request')，让自定义响应处理器捕获，而不是交给默认 handler 渲染 HTML
如何让 actionError 返回标准 {“code”, “message”, “data”}？
核心不是改 view，而是替换 renderException() 行为。最轻量方式是在 components 中注册自定义 error handler：
'errorHandler' => [
'class' => 'yii\web\ErrorHandler',
'errorAction' => 'api/error',
],
然后在 controllers/ApiController.php 实现 actionError()：
public function actionError()
{
$exception = Yii::$app->errorHandler->exception;
if ($exception !== null) {
Yii::$app->response->statusCode = $exception->statusCode ?: 500;
return [
'code' => $exception->getCode() ?: 50000,
'message' => $exception->getMessage(),
'data' => [],
];
}
}
-
$exception->statusCode只对HttpException子类有效，普通Exception是null，必须兜底设为500 - 这个 action 必须返回数组，Yii2 会自动 JSON 化；不能
echo或die - 千万别在
actionError里再throw异常，否则二次进入 error handler，可能死循环
400/401/403/404 状态码怎么映射到业务 code？
硬写 if ($exception instanceof \yii\web\BadRequestHttpException) 太脆弱。推荐用状态码查表映射：
$codeMap = [
400 => 10001,
401 => 10002,
403 => 10003,
404 => 10004,
500 => 50000,
];
$code = $codeMap[$exception->statusCode] ?? 50000;
- 不要依赖
$exception->getCode()做业务区分——它常是 0，且和 HTTP 状态码语义不一致 - 如果项目用了自定义异常类（如
ApiBadRequestException），可以在构造时显式传入业务 code，比查表更可控 - 注意：422（验证失败）这类状态码容易被忽略，要单独加进映射表，否则前端收不到明确提示
真正难的不是格式化，而是确保所有入口（控制器、过滤器、模型验证、数据库层抛出的异常）都经过同一套响应管道。漏掉一个 try/catch 或一个未注册的 filter，就可能冒出原始堆栈或 HTML 片段。
