Yii资源管理通过AssetBundle统一声明，核心判断依据是资源是否直接放在Web可访问目录：若在@webroot下则设basePath/@baseUrl，不设sourcePath；若在@npm等非Web目录则必须设sourcePath，此时basePath被自动覆盖。
Yii 的资源管理不是靠手动 link 或 script 标签硬写，而是通过 AssetBundle 类统一声明、依赖和发布。没配对 sourcePath 和 basePath，或混淆了 register() 的调用时机，资源就可能不加载、404，甚至重复引入。
AppAsset.php 里 $sourcePath 和 $basePath 到底怎么选
核心判断依据是：资源文件是否**直接放在 Web 可访问目录下**（比如 @webroot/css）。
- 如果 CSS/JS 就放在
frontend/web/css/下，直接设$basePath = '@webroot'和$baseUrl = '@web'，不用设$sourcePath—— 这样跳过发布步骤，更快也更直观 - 如果资源在
@app/assets/或@npm/bootstrap这类非 Web 目录下，就必须设$sourcePath（如'@npm/bootstrap'），让AssetManager把它复制到@webroot/assets/xxx后再引用 -
$basePath和$baseUrl在设了$sourcePath后会被自动覆盖，手动设了也无效；但不设$sourcePath时，它们就是关键路径
register() 调用失败的三个典型表现
资源没出现在 HTML 里，不一定是路径错，很可能是注册时机或上下文不对。
-
AppAsset::register($this)必须在视图中使用，且$this是yii\web\View实例 —— 在控制器、模型或布局外的普通 PHP 文件里调用会静默失效 - 在
beginBody()之后调用register()，JS 文件仍会注入<head>或底部，但执行顺序可能错乱；建议统一在视图顶部或beginPage()后立即注册 - 同一个 Bundle 在单次请求中多次
register()不会重复输出，但若两个 Bundle 都依赖yii\web\JqueryAsset，而其中一个把它禁用了（'yii\web\JqueryAsset' => false），另一个就会 JS 报错
禁用或替换默认 Asset 的正确写法
想关掉 jQuery 或换 CDN，不能只改 AppAsset::$depends，得动 assetManager 配置。
PigX UI 前端开发
下载
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
- 在
config/web.php的components里配assetManager：'assetManager' => [ 'bundles' => [ 'yii\web\JqueryAsset' => false, 'yii\bootstrap\BootstrapAsset' => [ 'css' => [], 'js' => [], ], 'yii\web\YiiAsset' => [ 'jsOptions' => ['position' => \yii\web\View::POS_HEAD], ], ], ] - 用 CDN 替代本地文件时，不要删
$js，而是用$jsOptions['async']或$jsOptions['integrity']补充属性，并确保$sourcePath为空（否则本地文件仍会被发布） -
false是彻底禁用，[]是清空内容但保留依赖关系 —— 前者更干净，后者可能被其他 Bundle 意外触发重载
用 npm 包时为什么总 404
常见原因是路径拼接错误，@npm 别名指向的是 node_modules 根目录，不是包内部。
立即学习“前端免费学习笔记（深入）”；
- 安装后检查真实路径：
ls node_modules/bootstrap/dist/css/bootstrap.min.css，对应代码里就得写'dist/css/bootstrap.min.css'，不是'css/bootstrap.min.css' -
$sourcePath = '@npm/bootstrap'是对的，但若写成'@npm/bootstrap/dist'就会找不到包根目录下的package.json，导致发布失败 - 开发时启用了
'appendTimestamp' => true，但 Nginx 没配好静态文件缓存头，会导致带时间戳的 URL 返回 404 —— 先关掉这个选项排查，再单独处理缓存策略
AssetManager 全局控制，但每个 AssetBundle 类里的 $publishOptions 可以覆盖它，比如强制不压缩、指定子目录。这些细节能解决跨环境路径不一致的问题，但文档里很少提，得看源码里的 AssetConverterInterface 和 Publisher 类才清楚。 
