<p>PostCSS插件必须返回接收root参数的函数，正确结构为module.exports = postcss.plugin('name', () => (root) => { / 处理逻辑 / })；遍历Declaration应优先用root.walkDecls并配合postcss-value-parser安全修改value；修改Rule.selector需用postcss-selector-parser解析后赋值，避免语义错乱；增删AST节点时须注意parent关系、source属性及节点脱离原树。</p>
PostCSS插件的核心不是操作字符串，而是遍历和修改AST节点；写错节点类型或漏掉root.walk遍历，插件就完全不生效。
如何正确创建一个PostCSS插件函数
PostCSS插件必须返回一个接收root参数的函数，这个root是AST的根节点。不能直接导出逻辑代码，也不能用async包裹整个插件函数（除非你明确处理Promise并返回result）。
常见错误：把插件写成立即执行函数、在顶层调用root.walk但没把它包进返回函数里、或误以为插件能直接读文件——PostCSS只传AST，不传路径或内容。
- 正确结构：
module.exports = postcss.plugin('plugin-name', () => (root) => { /* 处理逻辑 */ }); -
postcss.plugin只是语法糖，本质仍是返回(root) => {...} - 插件名必须唯一，会被用于错误堆栈和调试标识
怎么安全地遍历Declaration节点并修改value
绝大多数定制需求（如单位转换、z-index归一化、颜色校验）都落在Declaration节点上。但直接用root.walk可能命中注释、@规则等无关节点，应优先用root.walkDecls。
立即学习“前端免费学习笔记（深入）”；
注意node.value是原始字符串，修改它不会自动更新node.raws，可能导致SourceMap偏移或空格丢失。若需保留格式，应改用postcss-value-parser解析后再序列化。
- 简单替换可用：
decl.value = decl.value.replace(/px/g, 'rem'); - 带语义的转换必须用
postcss-value-parser，否则会破坏calc(10px + 2em)这类值 - 修改后建议调用
decl.value = newValue而非decl.setPropertyAndValue，后者会重置raws
为什么Rule节点的selector修改后样式失效了
直接赋值rule.selector = rule.selector.replace(/\./g, '_')看似可行，但PostCSS默认不触发selector重解析——rule.selectors数组不会同步更新，某些插件（如postcss-selector-parser）依赖该字段做后续处理。
更严重的是，修改selector字符串本身不影响rule.nodes（即内部Declaration），也不会通知父容器重新计算作用域。这会导致生成的CSS语法合法但语义错乱。
- 安全做法：用
postcss-selector-parser解析+修改+生成新字符串，再赋值给rule.selector - 避免直接操作
rule.selectors数组，它只是只读缓存 - 如果涉及复杂选择器逻辑（如:is()降级），必须重建整个Rule节点，不能仅改字符串
AST节点增删时最容易忽略的边界情况
删除节点用node.remove()没问题，但插入新节点时，parent.insertBefore和parent.append要求目标节点已脱离原树，否则会引发引用冲突或重复渲染。
另一个隐形坑是AtRule（如@media）内部嵌套Rule时，新插入的Declaration若没指定before/after位置，会默认追加到末尾，可能破坏原有声明顺序（影响CSS层叠）。
- 新增节点前先调用
newNode.parent = null确保干净 - 批量插入多个节点，别反复调用
append，改用parent.nodes.push(...nodes)更稳定 - 所有新增节点必须有
source属性（可复用原节点的node.source），否则SourceMap会丢失定位
AST操作没有“undo”机制，一旦节点被remove或replaceWith，原始引用就断了；调试时别依赖console.log(node)看实时状态，要用node.clone()做快照比对。
