Webpack CSS Loader在Windows正常但Linux下失效问题排查

问题 #

这套Webpack配置在Windows PowerShell中可正常运行，但在Linux控制台执行构建时CSS Loader无法正常工作，构建输出异常。Webpack配置代码如下：

const webpack = require('webpack');
const path = require('path');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const CopyPlugin = require("copy-webpack-plugin");

const MomentLocalesPlugin = require('moment-locales-webpack-plugin');

module.exports = {
  mode: 'production',
  watch: true,
  watchOptions: {
    ignored: /node_modules/,
    poll: 1000, // Check for changes every second
  },
  performance: {
    maxEntrypointSize: 1024000,
    maxAssetSize: 1024000
  },

  entry:{
    slick_style:'./node_modules/slick-slider/slick/slick.scss',
    sass_embeded:'./src/js/home.js',
  },
  output:{
    path: path.resolve( __dirname, '../site/'),
    filename:'js/[name].bundle.js',
    chunkFilename:'js/[name].bundle.[id].js',
  },
  externals: {
    jquery: 'jquery',
  },
  plugins: [
    new MiniCssExtractPlugin({
      linkType: "text/css",
      filename: 'css/[name].bundle.css',
      chunkFilename: "css/[name].bundle.[id].css",
    }),
    new MomentLocalesPlugin(),
    new MomentLocalesPlugin({
      localesToKeep: ['es-us'],
    }),

  ],
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          // 'style-loader',
          MiniCssExtractPlugin.loader,
          {
            loader: 'css-loader',
            options: {
              url: false,
              sourceMap: true,
            },
          },
          {
            loader: "sass-loader",
            options: {
              // Prefer `dart-sass`
              implementation: require("sass"),
              sourceMap: true,
              // sourceMapContents: false,
              sassOptions: {
                outputStyle: 'compressed',
              },
            },
          },
        ],
        include: path.resolve(__dirname, '/site/'),
      },
    ],
  },
}

请问Webpack跨Windows和Linux的配置规范是什么？是否遗漏了配置项？

排查与解决 #

当前配置的核心问题 #

1. 错误的include路径
   你的SCSS规则里include: path.resolve(__dirname, '/site/')完全不合理：site是输出目录，不是SCSS源文件所在目录；而且path.resolve搭配绝对路径/site/，在Linux下会解析为根目录的site文件夹，Windows下则是当前盘符根目录的site，直接导致源文件（比如node_modules里的slick.scss、src下的文件）被排除在规则匹配外，CSS Loader自然无法处理这些文件。
   直接删除这个include配置，或者改为包含你的SCSS源文件目录，比如：

include: [path.resolve(__dirname, 'src'), path.resolve(__dirname, 'node_modules/slick-slider')]

2. 重复实例化MomentLocalesPlugin
   你连续两次实例化了MomentLocalesPlugin，第二次配置会覆盖第一次，合并成一个即可：

new MomentLocalesPlugin({
  localesToKeep: ['es-us'],
}),

3. 生产模式下启用watch
   生产模式下默认不建议开启watch，如果需要在Linux下监听文件变化，确保文件系统权限正常，且poll配置可行，但建议仅在开发模式启用watch。

Webpack跨Windows/Linux的核心规范 #

• 路径处理必须用path模块：永远用path.resolve()或path.join()拼接路径，不要硬写/或\，比如path.resolve(__dirname, '../site')而非../site/。
• 注意文件系统大小写敏感：Linux区分文件名大小写（比如Home.js和home.js是两个文件），Windows不区分，确保代码里的导入路径和实际文件名大小写完全一致。
• 依赖安装保持一致：Windows和Linux下要安装相同版本的依赖，建议把package-lock.json或yarn.lock提交到版本库，避免依赖版本不一致引发问题。
• 避免使用Windows特有的命令或路径：不要在配置里引用C:\这类绝对路径，不要依赖Windows专属环境变量。
• 行尾换行符统一：可以通过.gitattributes设置* text=auto eol=lf，确保跨平台代码的换行符一致，避免Webpack监听时触发不必要的文件变更。

内容的提问来源于stack exchange，提问作者mauricio