Webpack配置报错“velocity is not defined”，外部依赖配置排查

Hey there, let's break down what's going wrong with your Webpack externals setup for Velocity, and how to fix it. It's super common to run into this mismatch between package names and global variables, so you're not alone!

Common Configuration Issues & Fixes #

1. Mismatched Package Name vs. Global Variable #

This is the most likely culprit. When you import Velocity in your code, you're probably using:

import Velocity from 'velocity-animate';

But if your externals config uses 'velocity' instead of 'velocity-animate' as the key, Webpack won't recognize it as an external dependency—so it either bundles the library in, or can't find the global variable at runtime.

Correct Externals Setup:
Make sure your webpack.config.js maps the exact package name to Velocity's global variable (note the capital V—Velocity mounts itself as window.Velocity):

module.exports = {
  // ... other config
  externals: {
    'moment': 'moment',
    'jquery': '$',
    'velocity-animate': 'Velocity' // This is the key line!
  }
};

2. Verify Velocity is Loaded Before Your Bundled Script #

Even with the right externals config, if your bundled JS runs before Velocity is loaded in the browser, you'll get the "not defined" error. Double-check your HTML load order:

<!-- Load Velocity FIRST -->
<script src="path/to/velocity.min.js"></script>
<!-- Then your bundled script -->
<script src="dist/your-bundled-code.js"></script>

3. Avoid Misusing Externals Formats #

If you're using regex or function-based externals instead of an object, you might be missing the critical mapping. For example, a regex like /^velocity$/ won't match 'velocity-animate', and Webpack assumes the global variable name matches the package name (which doesn't hold here—velocity-animate vs Velocity). Stick with the object format for explicit mappings like this.

4. Check Gulp-Webpack Integration #

Since you're using Gulp alongside Webpack, make sure your scripts.js Gulp task isn't overriding or omitting the externals config from webpack.config.js. You can add a quick console log in your Gulp task to verify the final Webpack config includes the velocity-animate entry:

// In your scripts.js Gulp task
const webpackConfig = require('./webpack.config.js');
console.log('Webpack Externals:', webpackConfig.externals); // Confirm 'velocity-animate' is present

Final Check #

After updating your externals, rebuild your bundle with Gulp/Webpack. If you inspect the bundled code, you should see that Webpack replaces the import Velocity from 'velocity-animate' line with a reference to the global Velocity variable instead of bundling the library itself.

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