postcss-color-mod-function 已停更且不兼容 PostCSS 8+，应替换为 postcss-color-function（支持 color() 标准语法和 legacy color-mod()），需配合 postcss-custom-properties 解析变量，并注意色彩空间与基础色完整性。
postcss-color-mod-function 不再维护，直接换用 postcss-color-function
这个插件早在 2019 年就停止更新，且与 PostCSS 8+ 不兼容，postcss-color-mod-function 会报 TypeError: Cannot read property 'type' of undefined 或解析失败。官方推荐迁移至 postcss-color-function（由 cssnext 团队维护），它支持标准 CSS Color Module Level 4 的 color() 函数语法，也兼容旧的 color-mod() 写法（需开启 legacy: true）。
实操建议：
- 卸载
postcss-color-mod-function：npm rm postcss-color-mod-function - 安装替代方案：
npm install postcss-color-function --save-dev - 在 PostCSS 配置中替换插件：
require('postcss-color-function')({ legacy: true })（保留原有color-mod()写法） - 若想逐步迁移到标准语法，可先不加
legacy: true，改用color(black alpha(50%))等写法
color-mod() 语法里 mod() 是动词，不是函数名
很多人误以为 color-mod() 是一个整体函数，实际它是 color() 函数 + mod() 调制器的组合，mod() 后面必须跟括号和调制规则，不能省略。常见错误写法：color-mod(black lightness(20%)) 看似合理，但 PostCSS 解析器会因缺少主色参数而报错 Expected color。
正确结构是：color-mod(<em>base-color</em> <em>modifier</em>)，其中 base-color 必须是有效颜色值（如 #333、hsl(120, 50%, 50%)、var(--primary)）。
立即学习“前端免费学习笔记（深入）”；
示例对比：
// ✅ 正确：基础色明确，mod() 完整 color-mod(#007bff lightness(20%) saturation(10%)) // ❌ 错误：缺基础色，解析中断 color-mod(lightness(20%)) // ❌ 错误：var() 未被提前解析，color-mod() 无法处理未定义变量 color-mod(var(--accent) alpha(80%))
动态颜色依赖 CSS 变量时，必须配合 postcss-custom-properties
color-mod() 和 color() 本身不解析 var(--x)，遇到变量只会原样透传，导致最终生成无效 CSS。比如 color-mod(var(--bg) lightness(10%)) 会被编译成相同字符串，浏览器无法识别。
解决路径只有一条：让变量值在进入 color-function 前就被展开。这需要 postcss-custom-properties 插件前置运行（顺序很重要）。
PostCSS 配置顺序示例：
module.exports = {
plugins: [
require('postcss-custom-properties')(), // 必须在 color-function 之前
require('postcss-color-function')({ legacy: true })
]
}
同时确保你的 CSS 变量已正确定义在 :root 或作用域内：
:root {
--primary: #007bff;
}
.btn {
background: color-mod(var(--primary) lightness(10%));
}
lightness/hue/saturation 在不同色彩空间下行为不一致
color-mod() 默认基于 HSL 调制，但如果你传入的是 #rgb 或 rgb()，插件会先转成 HSL 再调整，可能导致意外偏色——尤其当原始色接近黑白或饱和度极低时，lightness(20%) 可能让灰变暗到近黑，而非“提亮 20%”的直觉效果。
更可控的做法是显式指定色彩空间：
- 用
hsl()/hsla()作为基础色，保证调制逻辑可预测 - 避免对
rgb(255, 0, 0)直接hue(30deg)—— RGB 没有 hue 概念，插件会强制转换，结果可能偏离预期 - 调试技巧：临时把
color-mod(...)替换成对应静态值（如#0099ff），比对渲染差异
真正动态的颜色系统，最终往往要靠 CSS 自定义属性 + color() + JS runtime 更新变量来闭环，插件只是编译期辅助工具。
