PostCSS插件核心是接收CSS AST并遍历修改节点，不直接操作字符串；需按node.type区分decl/rule/atrule等类型，用decl.value/prop赋值、rule.append()插入，配合postcss-selector-parser和postcss-value-parser安全处理选择器与函数值。
理解 PostCSS 插件的核心工作方式
PostCSS 插件本质是接收 CSS AST（抽象语法树），遍历节点并修改它，最后由 PostCSS 输出结果。你不需手动解析字符串，也不该直接操作 rule.toString() 这类原始文本——那会绕过 AST 安全性，导致注释丢失、嵌套失效或媒体查询错位。
关键判断：插件是否只处理声明（decl）、规则（rule）还是更上层的 atrule？比如转换 color: red 就只关心 decl；而处理 @container 则必须监听 atrule。
- 所有节点类型都可通过
node.type判断，常见值为"decl"、"rule"、"atrule"、"comment" - 修改属性值用
decl.value = newValue，改属性名用decl.prop = newProp，不要用正则全局替换整个node.raws - 若需插入新声明，调用
rule.append()或decl.after()，而非拼接字符串
编写一个转换 font-size 的简单插件
假设需求：把所有 font-size: 16px 改成 font-size: 1rem，但仅限于根元素下的直接子元素（即 :root > * 匹配的声明）。
这需要两步判断：先定位到目标 rule，再在其子声明中筛选 font-size。不能只靠选择器字符串匹配，得用 postcss-selector-parser 安全解析。
立即学习“前端免费学习笔记（深入）”；
const postcss = require('postcss');
const selectorParser = require('postcss-selector-parser');
<p>module.exports = postcss.plugin('postcss-root-font-size', () => {
return (root) => {
root.walkRules((rule) => {
const parsed = selectorParser().astSync(rule.selector);
// 检查是否为 :root > *
const isRootDirectChild = parsed.nodes.some(node =>
node.type === 'selector' &&
node.nodes[0]?.type === 'pseudo' &&
node.nodes[0]?.value === ':root' &&
node.nodes[1]?.type === 'combinator' &&
node.nodes[1]?.value === '>' &&
node.nodes[2]?.type === 'universal'
);</p><pre class="brush:php;toolbar:false;"> if (isRootDirectChild) {
rule.walkDecls('font-size', (decl) => {
if (decl.value === '16px') {
decl.value = '1rem';
}
});
}
});}; });
注意：这里没用 rule.replaceWith() 或 rule.remove()，因为只是局部修改；也避免在 walkRules 中直接修改 rule.selector 字符串——那会破坏 AST 结构。
处理带单位计算或函数值的声明时容易踩的坑
当遇到 font-size: clamp(1rem, 2.5vw, 1.25rem) 或 background: linear-gradient(...) 时，直接正则替换 px 会出错。PostCSS 不会帮你解析函数体内部，decl.value 是完整字符串，但你不能假设它“可安全 split(' ')”。
- 对含函数的值，优先用
postcss-value-parser解析，它能区分函数、括号、数字、单位 - 不要写
decl.value.replace(/px/g, 'rem')—— 这会把background: #fff里的fff当作px替换 - 若需支持数学表达式（如
calc(16px * 1.2)），必须递归遍历postcss-value-parser返回的 nodes，只改unit类型节点 - 浏览器前缀（如
-webkit-font-smoothing）不是font-size，别误判为待转换属性
调试插件时如何快速定位问题节点
AST 调试最有效的方式不是 console.log 整棵树，而是打点 + 类型过滤。在遍历中加条件日志，比盲目输出更省时间。
- 在
walkDecls回调开头加if (decl.prop !== 'font-size') return;，聚焦目标 - 用
console.log(decl.source?.start, decl.parent?.selector)快速反查位置和上下文 - 遇到异常，检查
decl.parent是否为rule（可能在@keyframes内，此时parent是atrule） - 开发阶段可临时加
root.walk(node => { if (node.type === 'decl' && !node.parent) console.error('orphan decl:', node) })排查孤儿节点
真正难的不是写逻辑，而是搞清某个声明究竟在什么上下文中被创建——比如 CSS-in-JS 注入的样式可能没有 source，parent 可能是 root 而非 rule，这种边界情况不测就上线，后续排查成本极高。
