opencart 3.x+ 必须在控制器中用 $this->document->addstyle() 引入css，路径需相对于catalog目录且严格匹配主题目录结构，硬写或在tpl中调用css()均无效。
直接在 OpenCart 模板中引入 CSS，不能靠常规的 <link> 标签硬写进 TPL 文件——系统有自己的一套资源注入机制，硬加容易被忽略或重复加载。
OpenCart 3.x+ 的标准 CSS 引入方式：使用 $this->document->addStyle()
这是最可靠、兼容性最好、且能被系统自动去重和排序的方式。它必须写在控制器（Controller）里，而不是模板（TPL）中。
- 路径必须是相对于
catalog/目录的完整 URL 路径，比如catalog/view/theme/mytheme/stylesheet/stylesheet.css - 不能用相对路径（如
./stylesheet.css）或绝对路径（以/开头） - 推荐统一放在主题的
stylesheet/子目录下，便于管理 - 调用时机建议放在控制器的
index()方法开头或数据准备之后，确保样式在渲染前注册
示例（在 catalog/controller/common/header.php 中）：
$this->document->addStyle('catalog/view/theme/mytheme/stylesheet/custom.css');
模板引擎里不支持 css() 方法？那是 ZBuilder 框架的语法
你看到的 css('test') 或 css(['test1','test2']) 是 ZBuilder（常见于某些国产后台生成器或快速开发框架）的链式调用，**不是 OpenCart 原生能力**。在 OpenCart 的 TPL 文件里直接写 css() 会报错或完全无效。
- OpenCart 的 TPL 是纯 PHP 模板，不解析自定义方法调用
- 如果你在项目里混用了 ZBuilder 和 OpenCart，要注意它们的资源加载逻辑是隔离的
- 强行在 TPL 中用
<link>加载，可能造成样式重复、顺序错乱，或在 AJAX 渲染页面时失效
为什么不能在 header.tpl 里直接写 <link>？
可以写，但不推荐——它绕过了 OpenCart 的文档对象模型（$this->document），带来三个实际问题：
- 无法与其他模块的样式自动排序，比如插件加的 CSS 可能比你写的早或晚，导致覆盖失效
- CDN 或版本哈希（如
custom.css?v=1.2.3）需要手动维护，而addStyle()可配合配置动态拼接 - 多语言或多主题切换时，硬编码路径无法自动适配当前激活的主题目录
如果真要临时调试，可以写，但上线前务必迁移到控制器中。
主题目录结构对 CSS 路径的影响
OpenCart 严格依赖 catalog/view/theme/<theme_name>/</theme_name> 这一约定路径。CSS 文件必须放对位置，否则 addStyle() 找不到：
- 正确路径示例：
catalog/view/theme/default/stylesheet/bootstrap.css - 错误路径示例：
catalog/view/theme/default/css/bootstrap.css（OpenCart 不认css/子目录） - 主题名区分大小写，
MyTheme和mytheme在 Linux 服务器上是两个不同主题
检查当前激活主题名，务必和目录名完全一致，否则所有 addStyle() 路径都会 404。
最容易被忽略的点：路径拼写必须精确到每个字母和斜杠，且不能带查询参数或版本后缀——这些得由控制器逻辑动态追加，而不是写死在字符串里。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
