企業應用程式資料網格及圖表
webpack
與 webpack 合作感到驕傲

postcss-loader

免責聲明：postcss-loader是一個由社群成員維護的第三方套件，它可能沒有與 webpack 相同的支援、安全政策或授權，且並非由 webpack 維護。

npm node tests coverage size

Webpack 討論：discussion

PostCSS 聊天：chat-postcss

使用 PostCSS 處理 CSS 的載入器。

開始使用

您需要 webpack v5 才能使用最新版本。對於 Webpack v4，您必須安裝 postcss-loader v4。

首先，您需要安裝 postcss-loader 和 postcss

npm install --save-dev postcss-loader postcss

或

yarn add -D postcss-loader postcss

或

pnpm add -D postcss-loader postcss

然後將外掛程式新增到您的 webpack 設定檔中。例如

在以下設定檔中，使用了外掛程式 postcss-preset-env，它並未預設安裝。

file.js

import css from "file.css";

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [
                  [
                    "postcss-preset-env",
                    {
                      // Options
                    },
                  ],
                ],
              },
            },
          },
        ],
      },
    ],
  },
};

使用 設定檔 的替代用法

postcss.config.js

module.exports = {
  plugins: [
    [
      "postcss-preset-env",
      {
        // Options
      },
    ],
  ],
};

載入器會自動搜尋設定檔。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ["style-loader", "css-loader", "postcss-loader"],
      },
    ],
  },
};

並透過您偏好的方式執行 webpack。

選項

execute

類型

type execute = boolean;

預設：undefined

在 CSS-in-JS 中啟用 PostCSS 解析器支援。如果您使用 JS 樣式，postcss-js 解析器，請新增 execute 選項。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.style.js$/,
        use: [
          "style-loader",
          {
            loader: "css-loader",
          },
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                parser: "postcss-js",
              },
              execute: true,
            },
          },
        ],
      },
    ],
  },
};

postcssOptions

請參閱檔案 https://github.com/webpack-contrib/postcss-loader/blob/master/src/config.d.ts。

類型

import type { Config as PostCSSConfig } from "postcss-load-config";
import type { LoaderContext } from "webpack";

type PostCSSLoaderContext = LoaderContext<PostCSSConfig>;

interface PostCSSLoaderAPI {
  mode: PostCSSLoaderContext["mode"];
  file: PostCSSLoaderContext["resourcePath"];
  webpackLoaderContext: PostCSSLoaderContext;
  env: PostCSSLoaderContext["mode"];
  options: PostCSSConfig;
}

export type PostCSSLoaderOptions =
  | PostCSSConfig
  | ((api: PostCSSLoaderAPI) => PostCSSConfig);

預設：undefined

允許設定 PostCSS 選項 和外掛程式。

所有 PostCSS 選項都受到支援。有一個特殊的 config 選項，用於設定檔。其運作方式和設定方式如下所述。

我們建議不要指定 from、to 和 map 選項，因為這可能會導致原始碼對應表中的路徑錯誤。如果您需要原始碼對應表，請使用 sourcemap 選項。

對於大型專案，為了最佳化載入器的效能，最好在載入器設定檔中提供 postcssOptions，並指定 config: false。此方法可避免在編譯期間多次查詢和載入外部設定檔。

物件

設定 外掛程式

webpack.config.js (建議)

const myOtherPostcssPlugin = require("postcss-my-plugin");

module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            plugins: [
              "postcss-import",
              ["postcss-short", { prefix: "x" }],
              require.resolve("my-postcss-plugin"),
              myOtherPostcssPlugin({ myOption: true }),
              // Deprecated and will be removed in the next major release
              { "postcss-nested": { preserveEmpty: true } },
            ],
          },
        },
      },
    ],
  },
};

webpack.config.js (已棄用，將在下一版重大版本中移除)

module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            plugins: {
              "postcss-import": {},
              "postcss-short": { prefix: "x" },
            },
          },
        },
      },
    ],
  },
};

設定 語法

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            // Can be `string`
            syntax: "sugarss",
            // Can be `object`
            syntax: require("sugarss"),
          },
        },
      },
    ],
  },
};

設定 剖析器

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            // Can be `string`
            parser: "sugarss",
            // Can be `object`
            parser: require("sugarss"),
            // Can be `function`
            parser: require("sugarss").parse,
          },
        },
      },
    ],
  },
};

設定 字串化器

webpack.config.js

const Midas = require("midas");
const midas = new Midas();

module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            // Can be `string`
            stringifier: "sugarss",
            // Can be `object`
            stringifier: require("sugarss"),
            // Can be `function`
            stringifier: midas.stringifier,
          },
        },
      },
    ],
  },
};

函式

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(css|sss)$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: (loaderContext) => {
            if (/\.sss$/.test(loaderContext.resourcePath)) {
              return {
                parser: "sugarss",
                plugins: [
                  ["postcss-short", { prefix: "x" }],
                  "postcss-preset-env",
                ],
              };
            }

            return {
              plugins: [
                ["postcss-short", { prefix: "x" }],
                "postcss-preset-env",
              ],
            };
          },
        },
      },
    ],
  },
};

設定檔

類型

type config = boolean | string;

預設值：true

允許使用設定檔設定選項。設定檔中指定的選項會與傳遞給載入器的選項合併，載入器選項會覆寫設定檔中的選項。

設定檔

載入器會在目錄樹中搜尋以下位置的設定檔

  • package.json 中的 postcss 屬性
  • JSON 或 YAML 格式的 .postcssrc 檔案
  • .postcssrc.json、.postcssrc.yaml、.postcssrc.yml、.postcssrc.js 或 .postcssrc.cjs 檔案
  • 匯出物件的 postcss.config.js 或 postcss.config.cjs CommonJS 模組（建議使用）
設定檔範例

使用 object 表示法

postcss.config.js（建議使用）

module.exports = {
  // You can specify any options from https://postcss.dev.org.tw/api/#processoptions here
  // parser: 'sugarss',
  plugins: [
    // Plugins for PostCSS
    ["postcss-short", { prefix: "x" }],
    "postcss-preset-env",
  ],
};

使用 function 表示法

postcss.config.js（建議使用）

module.exports = (api) => {
  // `api.file` - path to the file
  // `api.mode` - `mode` value of webpack, please read https://webpack.dev.org.tw/configuration/mode/
  // `api.webpackLoaderContext` - loader context for complex use cases
  // `api.env` - alias `api.mode` for compatibility with `postcss-cli`
  // `api.options` - the `postcssOptions` options

  if (/\.sss$/.test(api.file)) {
    return {
      // You can specify any options from https://postcss.dev.org.tw/api/#processoptions here
      parser: "sugarss",
      plugins: [
        // Plugins for PostCSS
        ["postcss-short", { prefix: "x" }],
        "postcss-preset-env",
      ],
    };
  }

  return {
    // You can specify any options from https://postcss.dev.org.tw/api/#processoptions here
    plugins: [
      // Plugins for PostCSS
      ["postcss-short", { prefix: "x" }],
      "postcss-preset-env",
    ],
  };
};

postcss.config.js（已棄用，將在下一版重大版本中移除）

module.exports = {
  // You can specify any options from https://postcss.dev.org.tw/api/#processoptions here
  // parser: 'sugarss',
  plugins: {
    // Plugins for PostCSS
    "postcss-short": { prefix: "x" },
    "postcss-preset-env": {},
  },
};
設定檔串接

您可以在不同的目錄中使用不同的 postcss.config.js 檔案。設定檔查詢從 path.dirname(file) 開始，並向上遍歷檔案樹狀結構，直到找到設定檔檔案為止。

|– components
| |– component
| | |– index.js
| | |– index.png
| | |– style.css (1)
| | |– postcss.config.js (1)
| |– component
| | |– index.js
| | |– image.png
| | |– style.css (2)
|
|– postcss.config.js (1 && 2 (recommended))
|– webpack.config.js
|
|– package.json

設定好 postcss.config.js 之後，將 postcss-loader 新增到您的 webpack.config.js。您可以單獨使用它，或與 css-loader 搭配使用（建議使用）。

在 css-loader 和 style-loader 之前使用它，但在其他預處理器載入器（例如 sass|less|stylus-loader）之後使用它，如果您有使用這些載入器（因為 webpack 載入器從右到左/從下到上評估）。

webpack.config.js (建議)

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              importLoaders: 1,
            },
          },
          "postcss-loader",
        ],
      },
    ],
  },
};

boolean

啟用/停用自動載入設定檔。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            config: false,
          },
        },
      },
    ],
  },
};

字串

允許指定設定檔檔案的路徑。

webpack.config.js

const path = require("path");

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: "postcss-loader",
        options: {
          postcssOptions: {
            config: path.resolve(__dirname, "custom.config.js"),
          },
        },
      },
    ],
  },
};

sourceMap

類型

type sourceMap = boolean;

預設值：取決於 compiler.devtool 值

預設情況下，來源地圖的產生取決於 devtool 選項。除了 eval 和 false 值之外，所有值都會啟用來源地圖產生。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: "style-loader" },
          { loader: "css-loader", options: { sourceMap: true } },
          { loader: "postcss-loader", options: { sourceMap: true } },
          { loader: "sass-loader", options: { sourceMap: true } },
        ],
      },
    ],
  },
};

替代設定

webpack.config.js

module.exports = {
  devtool: "source-map",
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: "style-loader" },
          { loader: "css-loader" },
          { loader: "postcss-loader" },
          { loader: "sass-loader" },
        ],
      },
    ],
  },
};

implementation

類型

type implementation = object;

implementation 的類型應與 postcss.d.ts 相同

預設：postcss

特殊的 implementation 選項決定要使用哪個 PostCSS 實作。覆寫本機安裝的 postcss 的 peerDependency 版本。

此選項僅對下游工具作者真正有用，以簡化 PostCSS 7 到 8 的轉換。

function

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: "style-loader" },
          { loader: "css-loader" },
          {
            loader: "postcss-loader",
            options: { implementation: require("postcss") },
          },
          { loader: "sass-loader" },
        ],
      },
    ],
  },
};

字串

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          { loader: "style-loader" },
          { loader: "css-loader" },
          {
            loader: "postcss-loader",
            options: { implementation: require.resolve("postcss") },
          },
          { loader: "sass-loader" },
        ],
      },
    ],
  },
};

範例

SugarSS

您需要安裝 sugarss

npm install --save-dev sugarss

使用 SugarSS 語法。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.sss$/i,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: { importLoaders: 1 },
          },
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                parser: "sugarss",
              },
            },
          },
        ],
      },
    ],
  },
};

Autoprefixer

您需要安裝 autoprefixer

npm install --save-dev autoprefixer

使用 autoprefixer 將供應商前綴新增到 CSS 規則。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: { importLoaders: 1 },
          },
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [
                  [
                    "autoprefixer",
                    {
                      // Options
                    },
                  ],
                ],
              },
            },
          },
        ],
      },
    ],
  },
};

警告

postcss-preset-env 包含 autoprefixer，如果您已經使用預設，則不必另外新增。更多 資訊

PostCSS Preset Env

您需要安裝 postcss-preset-env

npm install --save-dev postcss-preset-env

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: { importLoaders: 1 },
          },
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [
                  [
                    "postcss-preset-env",
                    {
                      // Options
                    },
                  ],
                ],
              },
            },
          },
        ],
      },
    ],
  },
};

CSS 模組

什麼是 CSS 模組？請 閱讀。

postcss-loader 端不需要額外的選項。為了讓它們正常運作，請新增 css-loader 的 importLoaders 選項。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              modules: true,
              importLoaders: 1,
            },
          },
          "postcss-loader",
        ],
      },
    ],
  },
};

CSS-in-JS 和 postcss-js

您需要安裝 postcss-js

npm install --save-dev postcss-js

如果您想要處理以 JavaScript 編寫的樣式，請使用 postcss-js 剖析器。

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.style.js$/,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              importLoaders: 2,
            },
          },
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                parser: "postcss-js",
              },
              execute: true,
            },
          },
          "babel-loader",
        ],
      },
    ],
  },
};

結果您將能夠以以下方式撰寫樣式

import colors from "./styles/colors";

export default {
  ".menu": {
    color: colors.main,
    height: 25,
    "&_link": {
      color: "white",
    },
  },
};

警告

如果您使用 Babel，您需要執行以下操作才能讓設定運作

  1. 將 babel-plugin-add-module-exports 新增到您的設定檔。
  2. 您每個樣式模組只能有一個 預設 匯出。

萃取 CSS

使用 mini-css-extract-plugin。

webpack.config.js

const isProductionMode = process.env.NODE_ENV === "production";

const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  mode: isProductionMode ? "production" : "development",
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          isProductionMode ? MiniCssExtractPlugin.loader : "style-loader",
          "css-loader",
          "postcss-loader",
        ],
      },
    ],
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: isProductionMode ? "[name].[contenthash].css" : "[name].css",
    }),
  ],
};

發射資產

要從 PostCSS 外掛程式寫入資產到 webpack，需要在 result.messages 中新增訊息。

訊息應包含以下欄位

  • type = asset - 訊息類型（必要，應等於 asset）
  • file - 檔案名稱（必要）
  • content - 檔案內容（必要）
  • sourceMap - sourceMap
  • info - 資產資訊

webpack.config.js

const postcssCustomPlugin = (opts = {}) => {
  return {
    postcssPlugin: "postcss-custom-plugin",
    Once: (root, { result }) => {
      result.messages.push({
        type: "asset",
        file: "sprite.svg",
        content: "<svg>...</svg>",
      });
    },
  };
};

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [postcssCustomPlugin()],
              },
            },
          },
        ],
      },
    ],
  },
};

新增相依性、contextDependencies、buildDependencies、missingDependencies

相依性對於 webpack 來說是必要的，以便它了解何時需要對已變更的檔案執行重新編譯。

有兩種方式可以新增相依性

  1. (建議)。外掛程式可能會在 result.messages 中發出訊息。

訊息應包含以下欄位

  • type = dependency - 訊息類型（需要，應等於 dependency、context-dependency、build-dependency 或 missing-dependency）
  • file - 絕對檔案路徑（需要）

webpack.config.js

const path = require("path");

const postcssCustomPlugin = (opts = {}) => {
  return {
    postcssPlugin: "postcss-custom-plugin",
    Once: (root, { result }) => {
      result.messages.push({
        type: "dependency",
        file: path.resolve(__dirname, "path", "to", "file"),
      });
    },
  };
};

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [postcssCustomPlugin()],
              },
            },
          },
        ],
      },
    ],
  },
};

或者，您可以使用現成的外掛程式 postcss-add-dependencies。

  1. 在外掛程式中傳遞 loaderContext。

webpack.config.js

const path = require("path");

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                config: path.resolve(__dirname, "path/to/postcss.config.js"),
              },
            },
          },
        ],
      },
    ],
  },
};

postcss.config.js

module.exports = (api) => ({
  plugins: [
    require("path/to/postcssCustomPlugin.js")({
      loaderContext: api.webpackLoaderContext,
    }),
  ],
});

postcssCustomPlugin.js

const path = require("path");

const postcssCustomPlugin = (opts = {}) => {
  return {
    postcssPlugin: "postcss-custom-plugin",
    Once: (root, { result }) => {
      opts.loaderContext.addDependency(
        path.resolve(__dirname, "path", "to", "file"),
      );
    },
  };
};

postcssCustomPlugin.postcss = true;
module.exports = postcssCustomPlugin;

貢獻

如果您尚未閱讀，請花點時間閱讀我們的貢獻指南。

貢獻

授權

MIT

編輯此頁面·列印此頁面·跳至儲存庫
« 上一頁
less-loader
下一頁 »
sass-loader