Yii学习难点在于环境配置和目录结构认知，常见问题包括框架路径错误、gii访问限制、ActiveRecord类加载失败及路由约定不匹配，需逐一检查入口文件路径、模块配置、命名空间、数据库连接和URL规则。
Yii 框架本身不难学，但容易在「环境配置」和「目录结构认知」上卡住——尤其当你直接从 yiic webapp 或 composer create-project 开始，却没搞清 web/ 入口和 protected/（Yii 1.x）或 config/（Yii 2+）的职责边界时。
为什么刚跑起来就报错：require(): Failed opening required '.../framework/Yii.php'
这是 Yii 1.x 最常见的路径错误，本质是入口文件里 $Yii 变量指向了错误的框架位置。
- 检查
index.php中$Yii = dirname(__FILE__) . '/../../framework/Yii.php';这一行：如果framework文件夹不在项目根目录的上两级，就得手动改路径 - 别把整个 Yii 压缩包解压到
www目录下就完事——你真正要复制的是framework/文件夹，不是同级的demos/或requirements/ - Yii 2+ 用户跳过这一步：用
composer create-project生成的结构自带自动加载，web/index.php里的require __DIR__ . '/../vendor/autoload.php';才是关键
gii 打不开或提示“Access denied”，但代码生成器明明已启用
不是权限问题，而是默认只允许本地访问，且依赖 urlManager 和模块配置同时生效。
- 确认
config/web.php中'modules' => ['gii' => [...]]已定义，且'class' => 'yii\gii\Module' - Yii 2+ 默认加了 IP 白名单：
'allowedIPs' => ['127.0.0.1', '::1']，部署到测试服务器时必须显式放开，比如改成['192.168.1.*', '127.0.0.1'] - 确保
urlManager的'enablePrettyUrl' => true已开启，否则index.php?r=gii会 404；若没配 rewrite 规则，先临时设为false测试
写个 User::find()->one() 就报 Class 'User' not found
ActiveRecord 类没被自动加载，常见于模型文件命名、命名空间或数据库配置三者之一脱节。
- Yii 2+ 模型类名必须和文件名完全一致（大小写敏感），
User.php里必须是class User extends \yii\db\ActiveRecord - 检查
models/User.php顶部是否有namespace app\models;，且控制器中使用前写了use app\models\User; -
config/db.php中的'dsn' => 'mysql:host=localhost;dbname=testdb'必须真实可连，否则find()不报类错，但查不到数据——建议先用php yii migrate验证连接
真正卡人的从来不是语法，而是框架对“约定大于配置”的隐性依赖：比如 views/site/index.php 对应 SiteController::actionIndex()，漏掉一个字母或大小写，路由就静默失败。动手前花两分钟看一眼 config/web.php 里的 defaultRoute 和 urlManager.rules，比反复刷新页面有用得多。
