合法写法是直接在content_scripts数组项中与js同级声明css字段，值为相对于manifest.json的本地字符串数组，如["styles.css"]；路径不支持URL或绝对路径，且多文件按序注入、后覆盖前。
直接在 content_scripts 数组项里写 css 字段，路径必须是相对于 manifest.json 的本地相对路径，且必须是字符串数组——哪怕只引入一个文件，也得写成 ["styles.css"]，不是 "styles.css"。
content_scripts.css 字段怎么写才合法
这个字段和 js 是同级、并列的字段，不是嵌套结构，也不是子属性。常见错误是把它塞进 js 对象里，或者漏掉方括号。
-
css值必须是字符串数组，例如：["css/base.css", "css/theme.css"] - 路径不支持 URL、绝对路径或
chrome-extension://协议前缀，只认扩展包内真实存在的文件 - 文件必须实际打包进最终 crx 包；如果用了构建工具（如 webpack/vite），要确认
css数组里的路径对应输出目录中的文件位置 - 多个 CSS 按数组顺序注入，后一项的同名规则会覆盖前一项（和
<link>行为一致）
样式没生效？先查这三处硬性限制
Chrome 不报错，但样式“看不见”往往卡在这几个地方：
-
matches规则没命中目标页面：比如写了"matches": ["https://example.com/*"]，却访问了http://example.com（协议不匹配）或子域名未覆盖 - CSS 文件 404：打开 Chrome 控制台 → Application → Manifest → 展开
content_scripts条目，点开css列表里的路径，看是否显示 “Not found” - 选择器被页面样式压制：比如你写
.btn { color: red }，但页面用了.btn.primary:hover { color: blue !important }，你的规则权重不够，就得加权或用!important（慎用）
Shadow DOM 内的元素样式怎么覆盖
普通 content_scripts.css 注入的样式无法穿透 Shadow Root，默认不生效。
立即学习“前端免费学习笔记（深入）”；
- 若目标元素在自定义组件 shadowRoot 中，需改用影子选择器，例如：
:host { display: block; }或::slotted(*) { color: green; } - 或者放弃声明式注入，改用 JS 动态创建
<style>并 append 到对应 shadowRoot：shadowRoot.appendChild(styleEl) - 注意：
content_scripts.css本身不支持run_at，它总是在 DOM 构建前就注入；而 JS 注入时机由run_at控制，两者异步，别指望靠 JS 等 DOM 出来再插 style
什么时候该用 chrome.scripting.insertCSS 而不是 content_scripts.css
只有 Manifest V3 下需要**动态、按条件、运行时**注入 CSS 才用这个 API，比如响应用户点击 popup 后才加载某套主题样式。
- 必须在
manifest.json中声明"permissions": ["scripting"] - 不能在
content_scripts配置里用，它是独立于 content script 生命周期的 API - 调用前需确保目标 tab 已存在且可访问，常配合
chrome.tabs.query+chrome.scripting.executeScript使用 - 静态、固定、随页面加载即需的样式，一律走
content_scripts.css，更轻量、无权限要求、无需额外逻辑
最容易被忽略的是路径的“相对性”和 Shadow DOM 的隔离性——前者导致文件根本没加载，后者导致加载了也白加。调试时优先看 Application → Manifest 里的实际解析路径，再查 Elements 面板里该样式是否出现在 computed styles 中，而不是凭空猜。
