pdf生成工具对css支持方式各异：mpdf需本地磁盘路径或内联样式；html2pdf受限于同源策略，推荐内联或启用usecors；oxygen/dita-pdf要求css选择器严格匹配xml映射的xpath结构。
直接用 href 指向 Web 路径的 CSS 文件，在绝大多数 PDF 生成工具里都会失效——因为它们不走 HTTP 请求，而是读取本地文件系统路径或内联内容。
MPDF / Yii2 中 CSS 不生效的根源
MPDF 解析 HTML 时，<link rel="stylesheet" href="/css/style.css"> 这类相对或 Web URL 路径会被忽略。它只认真实存在的磁盘路径，比如 /var/www/myapp/web/css/style.css。
- 错误写法：
Yii::getAlias('@web') . '/css/style.css'→ 返回的是https://example.com/css/style.css，MPDF 打不开 - 正确写法：
Yii::getAlias('@webroot') . '/css/style.css'→ 返回服务器上真实路径，可被file_get_contents()读取 - 更稳妥的做法是把 CSS 内联进 HTML：
<style>body{font-size:14px}</style>，避免路径解析问题
html2pdf.js 中的 CSS 加载限制
html2pdf 在浏览器中运行，能加载同源 CSS，但遇到跨域、file:// 协议或未启用 CORS 的静态资源时会静默失败。
- 确保 CSS 文件与 HTML 同源（协议 + 域名 + 端口一致）
- 避免使用
@import或字体@font-face的远程地址，容易触发跨域拦截 - 调试时打开浏览器 DevTools → Network 标签页，过滤
css，看是否有 404 或 CORS 错误 - 推荐做法：把关键样式写在
<style></style>标签里，或用html2pdf().set({ html2canvas: { useCORS: true } })尝试绕过部分限制
Oxygen / DITA-PDF 中 CSS 选择器必须匹配 XPath 结构
Oxygen 的 PDF 发布不是渲染普通 HTML，而是先将 DITA XML 转成中间 HTML（如 merged.html），再用 CSS 控制样式。它的 class 名是 XML 结构映射出来的，不是你手写的。
- 别写
.section-title，要查merged.html里实际生成的 class，比如topic/title或section/title - 内容插入依赖
oxy_xpath()函数，例如页眉显示产品名：content: oxy_xpath('//*[contains(@class, "topic/prodname")]//text()'); - CSS 规则必须放在自定义 CSS 文件中，不能靠浏览器开发者工具临时改 —— 那些修改不会进 PDF 输出流程
- 调试核心路径：
out/pdf-css-html5/filename.merged.html，用 Chrome 打开它，开启打印预览模式（Ctrl+Shift+P→ 输入 “print”），再调样式
真正卡住人的往往不是“怎么加 CSS”，而是没意识到不同工具对 CSS 的消费方式根本不同：有的要文件路径，有的只吃内联，有的连 flex 都不支持，还有的要求 class 名必须和 XML 元素结构强绑定。选错路径，改半天也白搭。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
