PostCSS 运行器开发规范详解

PostCSS 运行器开发规范详解

postcss 项目地址: https://gitcode.com/gh_mirrors/pos/postcss

作为现代前端开发中不可或缺的CSS处理工具，PostCSS的强大之处在于其插件生态系统。而PostCSS运行器(Runner)则是连接用户与插件系统的桥梁。本文将深入解析PostCSS运行器的开发规范，帮助开发者构建符合标准的PostCSS处理工具。

运行器基础概念

PostCSS运行器是指那些通过用户定义的插件列表来处理CSS的工具，例如命令行工具或构建系统集成工具。它们负责协调PostCSS核心与插件之间的工作流程，确保CSS处理过程的高效与可靠。

API设计规范

插件参数应支持函数类型

当运行器使用配置文件时，必须采用JavaScript格式，以支持插件接收函数参数。这种设计允许插件实现动态逻辑，例如：

module.exports = [
  require('postcss-assets')({
    cachebuster: function (file) {
      return fs.statSync(file).mtime.getTime().toString(16)
    }
  })
]

这种灵活性使得插件能够根据文件内容或环境变量动态调整行为，大大增强了处理能力。

处理流程规范

必须设置from和to选项

为确保源映射(source map)的正确生成和更友好的错误提示，运行器必须明确指定输入输出路径：

processor.process({ from: file.path, to: file.path })

即使工具不直接处理文件写入(如gulp转换流)，也应将这两个选项设置为相同值。

仅使用异步API

PostCSS运行器必须使用异步API，原因有三：

1. 同步API仅用于调试目的
2. 异步性能更优
3. 兼容异步插件

正确用法：

processor.process(opts).then(result => {
  // 处理完成回调
});

仅依赖公开API

运行器必须严格使用PostCSS的公开API，避免依赖任何未文档化的属性或方法，这些内部实现可能在次要版本更新中发生变更。

依赖管理规范

监听依赖变更重建

PostCSS插件可以通过result.messages声明文件或目录依赖。运行器应当监听这些依赖，并在它们变更时触发重建：

for (let message of result.messages) {
  if (message.type === 'dependency') {
    watcher.addFile(message.file)
  } else if (message.type === 'dir-dependency' && message.glob) {
    watcher.addPattern(file.join(message.dir, message.glob))
  } else if (message.type === 'dir-dependency') {
    watcher.addPattern(file.join(message.dir, '**', '*'))
  }
}

对于目录依赖，默认应递归监听，但当消息包含glob属性时，应仅监听匹配该模式的文件。

输出处理规范

优雅处理语法错误

为避免吓到不熟悉JavaScript的CSS开发者，运行器应当优雅处理CSS语法错误，而非显示JS调用栈：

processor.process(opts).catch(error => {
  if (error.name === 'CssSyntaxError') {
    process.stderr.write(error.message + error.showSourceCode())
  } else {
    throw error
  }
})

显示警告信息

运行器必须输出result.warnings()中的警告信息：

result.warnings().forEach(warn => {
  process.stderr.write(warn.toString())
})

支持分离源映射

虽然PostCSS默认内联源映射，但运行器应提供选项将源映射写入单独文件：

if (result.map) {
  fs.writeFile(opts.to + '.map', result.map.toString())
}

文档与发布规范

英文文档基础

README.md必须使用英语编写，这是国际开源社区的基本要求。当然也欢迎提供其他语言版本，但需明确命名(如README.ja.md)。

维护变更日志

运行器必须维护独立的变更日志文件(ChangeLog.md或History.md)，详细记录每个版本的变更内容。建议遵循Keep A Changelog规范，并采用语义化版本(SemVer)。

正确的依赖声明

为避免不同插件使用不同版本的PostCSS导致AST破坏，运行器应将postcss声明为peerDependencies：

{
  "peerDependencies": {
    "postcss": "^8.0.0"
  }
}

使用postcss-runner关键词

发布到npm的PostCSS运行器应在package.json中包含postcss-runner关键词，这有助于生态系统的健康发展。

结语

遵循这些规范开发的PostCSS运行器，将能够提供一致的用户体验，确保与生态系统中各种插件的良好兼容性，同时为开发者提供强大的CSS处理能力。无论是构建命令行工具还是集成到现有构建系统，这些准则都是确保工具质量的重要保障。

postcss 项目地址: https://gitcode.com/gh_mirrors/pos/postcss