Yii2高频问题集中在环境、路径、权限、配置、CSRF五方面：启动类错误需检查docroot和YII_ENV；请求类错误重在CSRF令牌一致性和Accept头兼容；资产类须配好bower插件与镜像；上传类务必用@webroot绝对路径并赋写权限。
Yii2 报错看着多，其实集中在几个关键环节：环境没配齐、路径没对上、权限没给够、配置没生效、CSRF 或 Accept 头不兼容。下面按真实高频场景分类整理，不列冷门异常，只讲你十有八九会遇到的二十个典型问题及其直击要害的解决思路。
一、启动与入口类错误（5个）
这类错误发生在项目刚跑起来时，根本没进控制器就卡住。
- “Document root does not exist”：Advanced 版本没指定 --docroot。必须明确写 php yii serve --docroot="frontend/web/" 或 --docroot="backend/web/"，不能省略。
- “Class 'Yii' not found”：index.php 中 require 的 autoload.php 路径错。检查是否在 web/ 目录下运行，且 __DIR__ . '/../vendor/autoload.php' 真实存在——常见于用 phpEnv 或绿色包，vendor 目录根本没生成。
- “require(): Failed opening required …”：PHP 没启用 openssl 或 mbstring 扩展。执行 php -m | grep -E "openssl|mbstring" 验证，缺哪个就在 php.ini 里取消对应 extension= 行前的分号。
- “InvalidParamException: The view file does not exist”：视图路径写错或大小写不符。Linux 下 @app/views/Site/index.php ≠ @app/views/site/index.php；先用 Yii::getAlias('@app') 确认根目录，再手动进文件系统找。
- Gii 打不开，报 “The file or directory to be published does not exist: …/gii/assets”：YII_ENV 没设为 'dev'。检查 web/index.php 开头是否为 defined('YII_ENV') or define('YII_ENV', 'dev');，不能写成 'development' 或全大写。
二、跳转与请求类错误（5个）
用户点一下就白屏、卡住或 400/500，多是 HTTP 协议层或安全机制没对齐。
- 登录后不跳转，尤其 IE10 及更早版本空白：老 IE 发送 Accept: application/x-ms-application，而 Yii2 默认只认 text/html 和 application/xhtml+xml。在 config/web.php 的 components['user'] 中加 'acceptableRedirectTypes' => ['text/html', 'application/xhtml+xml', 'application/x-ms-application']。
- AJAX 提交报 400 “Unable to verify your data submission”：CSRF 令牌不一致。别用 \yii::$app->request->csrfToken 动态取，应读页面已有 meta：var token = $('meta[name="csrf-token"]').attr('content');；提交字段名必须和 config 中 'csrfParam' => '_csrf-frontend' 完全一致。
- 表单提交后 400，但页面没报错：隐藏域 name 写错了，比如写了 ，但 config 设的是 '_csrf-backend'。name 值必须一字不差匹配 csrfParam。
- 访问任意 URL 都 500 白屏，日志空、浏览器无堆栈：错误被静默吞了。三件事立刻做：① index.php 开头加 defined('YII_DEBUG') or define('YII_DEBUG', true);；② chmod -R 775 runtime/；③ Nginx 加 fastcgi_intercept_errors off;。
- 自定义 404 页面不显示，直接出 Nginx 默认页：errorAction 没配或被 Web 服务器拦截。在 config/web.php 的 components['response'] 里加 'errorAction' => 'site/error'；同时确认 Nginx/Apache 没把 /site/error 这类路由提前 404 掉。
三、资产与资源类错误（5个）
样式乱、JS 不执行、Gii/GiiAsset 加载失败、前端库报 404，基本都出在 assets 目录或 bower-asset 插件上。
- web/assets/ 下没生成哈希目录，CSS/JS 全部 404：assets 目录没写权限。执行 sudo chgrp -R www-data web/assets && sudo chmod -R g+rwxs web/assets && sudo chmod g+rx web/（父目录也要可进入）。
- 报错 “The file or directory to be published does not exist: vendor/bower/jquery/dist”：bower-asset 插件缺失或太旧。运行 composer global require "fxp/composer-asset-plugin:^1.4.10"，再删 vendor/ 和 composer.lock，重装。
- 用了国内镜像却还是拉不到 jquery/bootstrap：只配了 packagist 镜像，漏了 asset-packagist。补上：composer config -g repos.asset-packagist composer https://asset-packagist.org。
- 上传图片后页面显示 404，但文件实际存到了 uploads/：URL 路径没映射到 webroot。确保 saveAs() 用的是 Yii::getAlias('@webroot') . '/uploads/filename.jpg'，而非相对路径或硬编码路径。
- runtime/ 下 log 文件为空，但明显有异常发生：runtime/logs/ 权限不对或属组不是 web 用户。chgrp www-data runtime/ && chmod -R g+rwxs runtime/，并确认 runtime/ 上层目录（如 basic/）对组有 r-x 权限。
四、模型与上传类错误（5个）
表单能提交、验证能过，但文件就是不落地、数据库不更新、关联查不出来——这类“静默失败”最耗时间。
- UploadedFile::saveAs() 返回 false，没报错也没提示：uploadPath() 返回的是 'basic/web/uploads/' 这种字符串，不是物理路径。改用 return Yii::getAlias('@webroot') . '/uploads/'; 并确保该目录存在且可写。
- mkdir(): Permission denied in UploadForm.php：PHP 进程用户（如 www-data）对 web/uploads/ 没写权限。Linux/macOS 执行 chmod 775 web/uploads/；Windows 检查 IIS 用户或 Apache 服务账户对该目录有“修改”权限。
- 上传成功但数据库没更新，或关联查询返回 null：ActiveRecord 关联定义错误。检查 hasOne()/hasMany() 中的 'viaTable' 或 'through' 是否拼错；外键字段名是否和数据库一致（如 user_id ≠ userId）。
- 搜索时出现 N+1 查询，列表页慢得像卡死：没用 with() 预加载。例如 User::find()->with('profile', 'orders')->all()，而不是在循环里反复 $user->profile。
- 数据库连接失败，报 “Connection refused” 或 “Access denied”：config/db.php 中 host、username、password 错，或 MySQL 服务根本没开。先命令行 mysql -u root -p 测试能否连；再确认 db 组件是否在 config/web.php 的 components 数组里正确注册。
