Webpack 4.8下Serverless-webpack部署脚本挂起，如何排查？

Problem Background #

I'm working with Serverless and serverless-webpack, using the following configurations:

webpack.config.js:

const path = require('path'); 
const nodeExternals = require('webpack-node-externals'); 

module.exports = { 
  entry: { lambda: './lambda.js', }, 
  output: { 
    libraryTarget: 'commonjs', 
    path: path.join(__dirname, '.webpack'), 
    filename: '[name].js', 
  }, 
  target: 'node', 
  externals: [nodeExternals()], 
  module: { 
    rules: [
      { 
        test: /\.js$/, 
        loader: 'babel-loader', 
        include: __dirname, 
        exclude: /node_modules/, 
      }, 
      { test: /\.json$/, loader: 'json-loader', }
    ], 
  }, 
  stats: "verbose", 
}; 

serverless.yml:

plugins: 
  - serverless-webpack 
  - serverless-secrets-plugin 
  - serverless-plugin-split-stacks 
  - serverless-offline 
custom: 
  webpack: 
    webpackConfig: ./webpack.config.js 
  stage: ${opt:stage, self:provider.stage} 
provider: 
  name: aws 
  runtime: nodejs8.10 
functions: 
  lambdaFn: 
    handler: lambda.fn 
    events: 
      - http: GET /foo 

When running the command node ./node_modules/.bin/serverless offline -p 3001 -s local with Webpack 4.8, the console only prints Serverless: Bundling with Webpack..., the Node process sits at 0% CPU, and the script hangs indefinitely. Downgrading to Webpack 3.12 resolves the issue. How can I debug this?

Actionable Debugging Steps #

Let’s break down how to pinpoint the cause of this hang:

1. Enable Webpack's Detailed Debug Logging
   Webpack’s debug mode will show you every step of the bundling process, making it easy to spot where it gets stuck. First, add the debug flag to your webpack config:

   module.exports = {
     // ... existing config
     debug: true,
     stats: 'verbose'
   };
   

   Then run your serverless command with Webpack’s debug environment variable:

   DEBUG=webpack:* node ./node_modules/.bin/serverless offline -p 3001 -s local
   

   Look for the last logged action before the hang—this will tell you exactly which phase or module is causing the freeze.

2. Verify Serverless-Webpack and Webpack 4 Compatibility
   Webpack 4 introduced significant breaking changes, and older versions of serverless-webpack don’t support it. Check your current version:

   npm list serverless-webpack
   

   You’ll need serverless-webpack v5.0.0 or newer for Webpack 4 support. If you’re on an older version, upgrade it:

   npm install serverless-webpack@latest --save-dev
   

3. Test Without webpack-node-externals
   The nodeExternals() plugin can sometimes cause deadlocks or resolution issues with Webpack 4. Temporarily comment out the externals line in your webpack config:

   // externals: [nodeExternals()],
   

   If bundling completes after this, update webpack-node-externals to v2.0.0+ (the first version compatible with Webpack 4).

4. Add the Webpack Progress Plugin
   This plugin logs real-time progress of the bundling process, so you can see exactly which module is being processed when it hangs. Add it to your webpack config:

   const webpack = require('webpack');
   
   module.exports = {
     // ... existing config
     plugins: [
       new webpack.ProgressPlugin((percentage, message) => {
         console.log(`Webpack: ${Math.round(percentage * 100)}% - ${message}`);
       })
     ]
   };
   

   Run your command again—this will show you the exact step where execution stops.

5. Enable Serverless Verbose Logging
   Serverless’s verbose mode will show you how plugins interact, which can reveal if another plugin (like serverless-secrets-plugin or serverless-plugin-split-stacks) is causing a deadlock with serverless-webpack. Run the command with:

   node ./node_modules/.bin/serverless offline -p 3001 -s local --verbose
   

   Look for logs around plugin initialization and hook execution to spot delays.

6. Check Loader Compatibility
   Webpack 4 changed loader requirements:

   • babel-loader v8.0.0+ is required for Webpack 4 (this also needs Babel 7+). Check your version with npm list babel-loader and upgrade if needed.
   • Webpack 4 natively handles JSON files, so you can remove the json-loader rule entirely—it’s no longer needed.

7. Gradually Simplify Your Config
   If you’re still stuck, strip down your setup to the bare minimum to isolate the issue:

   • Remove all Serverless plugins except serverless-webpack and serverless-offline
   • Simplify your webpack config to only include entry, output, and target
   • Temporarily remove any custom Babel presets/plugins from your .babelrc
     Add back components one by one until the hang reoccurs—this will pinpoint exactly which part of your setup is causing the problem.

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