跳转到主要内容
用同一条管线,在扩展页面和 content script 中以一致的方式转换 CSS。当你需要 Autoprefixer 之类的插件或现代 CSS 转换时,就该用 PostCSS。 Extension.js 会检测 PostCSS 配置,并在需要时自动应用 postcss-loader。

什么场景适合用 PostCSS

  • 你需要在扩展样式里做自动前缀或现代 CSS 转换。
  • 你希望在 popup/options/sidebar/content script 中共用一条 CSS 转换管线。
  • 你正在使用 Tailwind 或基于插件的样式处理。

PostCSS 的能力

模板示例

Tailwind + PostCSS 起步模板

当你想要一套可用的 PostCSS 设置,并搭配 Tailwind 与组件化 UI 时,用这个模板。 sidebar-shadcn screenshot
仓库:examples/sidebar-shadcn

检测和配置文件

Extension.js 会在项目根目录按以下顺序检查 PostCSS 配置文件,并使用找到的第一个:
  • .postcssrc
  • .postcssrc.json
  • .postcssrc.yaml
  • .postcssrc.yml
  • .postcssrc.ts / .postcssrc.cts / .postcssrc.mts
  • .postcssrc.js / .postcssrc.cjs / .postcssrc.mjs
  • postcss.config.ts / postcss.config.cts / postcss.config.mts
  • postcss.config.js / postcss.config.cjs / postcss.config.mjs
  • .config/ 文件夹里同样的 postcssrc 名称
当一个项目同时保留两者时,rc 文件优先于 postcss.config.*。在 package.json 设置了 "type": "module" 的项目里,以纯 .js 结尾的配置排在其他所有名称之后尝试。 它也能识别 package.json 中的 postcss 配置。

在现有扩展中使用 PostCSS

安装 PostCSS 依赖:

创建 postcss.config.js

用法

在扩展页面中按常规方式导入样式:
对于 content script,单纯的导入本身不会给任何东西加上样式。像 content 模板那样,把处理后的样式表加载进你的 shadow root:
Extension.js 在这两种上下文中都会应用 PostCSS,但打包方式不同(页面走 css 管线,content script 走资源管线)。

与 Tailwind 的相互作用

  • 检测到 Tailwind 时,Extension.js 可以自动触发 PostCSS 设置。
  • Extension.js 同时支持 Tailwind v3 和 v4,会根据检测到的版本选择相应插件。
  • 在 ECMAScript 模块(ESM)项目里,如果 PostCSS 配置使用了不兼容的 CommonJS(CJS)模式,Extension.js 可能会绕过你的配置,转而注入兼容性插件。

配置或插件无法加载时

从 4.1.41 之后的版本起,Extension.js 无法使用的 PostCSS 配置会被搁置,构建在没有它的情况下继续:
  • 配置文件抛出错误,或导入失败。
  • 配置导出的函数抛出错误。
  • plugins 既不是数组,也不是以插件名为键的对象。
警告会给出该文件,并说明它的插件都不会运行。样式仍会编译,所以请修复或删除这个文件。你的 Node.js 版本无法加载的 TypeScript 配置会原样交给 postcss-loader。从 4.1.41 之后的版本起,Extension.js 会自己读取 YAML rc 文件,它的插件路径从你的项目解析。 配置中列出但无法解析的插件也会被跳过。警告为 Couldn't resolve the PostCSS plugin <name>.,该插件本应生成的样式不会出现在输出中。 即使每条样式规则都读取同一份配置,这些警告在每次构建中也只打印一次。在 dev 期间,只有当问题消失后又出现时,警告才会再次打印。 从 4.2.0 之后的版本起,这些设置警告带有代码 W_CSS_NOT_APPLIED。这包括本节和下面列表中的警告,以及配置中某条规则给样式表文件设置了 Extension.js 不会应用的 type 时的警告。只有 dev 需要重启的提示保留 W_RESTART_REQUIRED。4.2.0 及之前的版本给它们全部的是 W_RESTART_REQUIRED。 从 4.1.41 之后的版本起:
  • postcss.config.json、postcss.config.yaml 和 postcss.config.yml 是 PostCSS 从不读取的名称。构建会发出警告,并给出应改成的 rc 文件名,比如 .postcssrc.json。
  • Tailwind 只从你的项目中获取。缺少它的 PostCSS 插件时,会有一条警告给出安装命令。
  • 在 dev 期间,对 PostCSS 或 Tailwind 配置的修改会在下一次构建时生效。
  • 增加或移除 PostCSS 步骤的改动会警告 dev 需要重启。
  • 配置中的 parser、syntax、stringifier 和 map 选项会与其插件一起生效。以字符串命名的模块从你的项目中解析。

最佳实践

  • 让插件链保持精简、显式(例如 autoprefixer、postcss-preset-env)。
  • 确认配置文件格式(.mjs/.cjs)与项目的 module type 一致。
  • 让 Tailwind 与 PostCSS 的版本保持对齐,以避免插件解析错配。
  • 优先使用共享的样式入口文件,让各个扩展界面的处理结果保持一致。

下一步