PostCSS 运行器指南

PostCSS 运行器是一个通过用户定义的插件列表处理 CSS 的工具；例如，postcss-cli 或 gulp‑postcss。这些规则对于任何此类运行器都是强制性的。

对于单插件工具（如 gulp-autoprefixer），这些规则不是强制性的，但强烈建议使用。

另请参阅 ClojureWerkz 的建议，了解开源项目。

1. API

1.1. 在插件参数中接受函数

如果你的运行器使用配置文件，则必须用 JavaScript 编写，以便它可以支持接受函数的插件，例如 postcss-assets

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

2. 处理

2.1. 设置 `from` 和 `to` 处理选项

为了确保 PostCSS 生成源映射并显示更好的语法错误，运行器必须指定 from 和 to 选项。如果你的运行器不处理写入磁盘（例如，gulp 转换），则应将这两个选项都指向同一个文件

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

2.2. 仅使用异步 API

PostCSS 运行器必须仅使用异步 API。同步 API 仅用于调试，速度较慢，并且无法与异步插件一起使用。

processor.process(opts).then(result => {
  // processing is finished
});

2.3. 仅使用公共 PostCSS API

PostCSS 运行器不得依赖于未记录的属性或方法，这些属性或方法可能会在任何次要版本中发生更改。公共 API 在 API 文档中进行了描述。

3. 依赖项

3.1. 在依赖项更改时重新构建

PostCSS 插件可以通过将消息附加到 result 来声明文件或目录依赖项。运行器应监视这些依赖项，并确保在它们更改时重新构建 CSS。

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, '**', '*'))
  }
}

默认情况下应递归监视目录，但 dir-dependency 消息可能包含一个可选的 glob 属性，指示目录中依赖于哪些文件（例如 **/*.css）。如果指定了 glob，则运行器在可能的情况下应仅监视与 glob 模式匹配的文件。

4. 输出

4.1. 对于 `CssSyntaxError`，不显示 JS 堆栈

PostCSS 运行器不得为 CSS 语法错误显示堆栈跟踪，因为运行器可以被不熟悉 JavaScript 的开发人员使用。相反，优雅地处理此类错误

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

4.2. 显示 `result.warnings()`

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

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

另请参阅 postcss-log-warnings 和 postcss-messages 插件。

4.3. 允许用户将源映射写入不同的文件

默认情况下，PostCSS 会在生成的文件中内联源映射；但是，PostCSS 运行器必须提供一个选项来将源映射保存在另一个文件中

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

5. 文档

5.1. 用英语记录你的运行器

PostCSS 运行器的 README.md 必须用英语编写。不要担心你的英语水平，因为开源社区会帮你纠正错误。

当然，欢迎你用其他语言编写文档；只需为它们命名适当的名称（例如 README.ja.md）。

5.2. 维护变更日志

PostCSS 运行器必须在单独的文件中描述所有版本的更改，例如 ChangeLog.md、History.md 或使用 GitHub Releases。访问 Keep A Changelog 以获取有关如何编写其中一个的更多信息。

当然，你应该使用 SemVer。

5.3. `package.json` 中的 `postcss-runner` 关键字

为 npm 编写的 PostCSS 运行器必须在其 package.json 中具有 postcss-runner 关键字。此特殊关键字将有助于反馈有关 PostCSS 生态系统的信息。

对于未发布到 npm 的软件包，这不是强制性的，但如果允许软件包格式包含关键字，则建议这样做。

5.4. 将 `postcss` 保持为 `peerDependencies`

AST 可能因不同插件中不同的 postcss 版本而中断。不同的插件可以使用不同的节点创建器（如 postcss.decl()）。

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