Drupal出现$ is not a function错误：本地正常线上异常求助

Hey there! I’ve run into this exact headache with Drupal before, so let me walk you through the most common fixes that usually bridge the gap between your working local setup and the misbehaving live site.

Common Causes & Solutions #

1. Drupal’s jQuery No-Conflict Mode is Blocking $ #

Drupal enables jQuery’s noConflict() mode by default, which means the shorthand $ isn’t available globally—this is often why your code works locally (maybe you’re testing with a setup that skips this, or you’ve got a local override) but breaks live.

Fix: Wrap all your code that uses $ in a jQuery ready function that aliases $ safely:

jQuery(document).ready(function($) {
  // Your code using $ goes here
  $('.custom-button').click(function() {
    // Do something
  });
});

If you’re registering your script via Drupal’s libraries system, also make sure you declare a dependency on core jQuery in your .libraries.yml file:

my_custom_script:
  js:
    js/my-script.js: {}
  dependencies:
    - core/jquery

2. JS Aggregation/Minification is Causing Chaos #

Local environments typically have JS aggregation disabled (check /admin/config/development/performance), but live sites almost always turn it on to boost performance. Aggregation can reorder scripts, or minification might break your code if there are subtle syntax errors (like missing semicolons).

Fix:

• Temporarily disable aggregation on the live site (only for debugging!)—if the error vanishes, clear all caches, re-enable aggregation, and test again.
• Run your script through a linter (like ESLint) to catch syntax issues that minifiers might choke on.

3. Cache Discrepancies Between Environments #

Local setups often have caching turned off, but live sites rely on full page caching, asset caching, and browser caching. Old, outdated versions of your script might be loading instead of your updated code.

Fix:

• Clear all Drupal caches on the live site (use the performance page or run drush cr if you have Drush access).
• Add a version query string to your script filename (e.g., my-script.js?v=1.1) to force browsers to load the latest version instead of using cached copies.

4. External jQuery Conflicts (If You’re Using a CDN) #

If you’re loading jQuery from an external CDN instead of Drupal’s core library, the live site might block it (due to CORS policies) or load a version that’s incompatible with your code.

Fix: Stick to Drupal’s core jQuery library whenever possible. If you must use a CDN, double-check that it’s properly configured in your Drupal settings and that the version matches what your code expects.

Start with wrapping your code in the jQuery ready function with the $ alias—this is the most frequent fix for this error in Drupal. If that doesn’t work, move on to checking aggregation and cache issues next.

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