Webpack加载jQuery模块最佳方法及PHP项目前端资源配置方案

嘿，我来帮你一步步把PHP项目的前端资源切换到Webpack + NPM管理，彻底告别复制粘贴文件的日子！下面是针对你的场景的完整配置方案：

1. 初始化NPM项目并安装依赖 #

首先在你的项目根目录打开终端，先快速生成package.json：

npm init -y

然后安装核心依赖和开发工具：

# 业务依赖：jQuery、highlight.js
npm install jquery highlight.js

# 开发依赖：Webpack及转译、样式处理工具
npm install --save-dev webpack webpack-cli babel-loader @babel/core @babel/preset-env css-loader style-loader webpack-dev-server

最终你的package.json会类似这样（重点关注scripts字段，用来执行打包命令）：

{
  "name": "your-php-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "build": "webpack --mode production", // 生产环境压缩打包
    "dev": "webpack --mode development --watch" // 开发环境实时监听修改并打包
  },
  "dependencies": {
    "highlight.js": "^11.9.0",
    "jquery": "^3.7.1"
  },
  "devDependencies": {
    "@babel/core": "^7.23.7",
    "@babel/preset-env": "^7.23.7",
    "babel-loader": "^9.1.3",
    "css-loader": "^6.8.1",
    "style-loader": "^3.3.3",
    "webpack": "^5.89.0",
    "webpack-cli": "^5.1.4",
    "webpack-dev-server": "^4.15.1"
  }
}

2. 配置Webpack核心文件（webpack.conf.js） #

在项目根目录创建webpack.conf.js，重点解决jQuery全局可用的问题（很多老插件依赖全局的$或jQuery变量）：

const path = require('path');
const webpack = require('webpack');

module.exports = {
  // 前端资源入口：你的主JS文件
  entry: './resources/app.js',
  // 打包输出配置：将产物放到PHP项目的公共资源目录
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'public/assets'),
    publicPath: '/assets/' // PHP页面引用资源时的基础路径
  },
  plugins: [
    // 关键配置：自动在所有模块中注入jQuery，无需手动import就能用$和jQuery
    new webpack.ProvidePlugin({
      $: 'jquery',
      jQuery: 'jquery',
      'window.jQuery': 'jquery'
    })
  ],
  module: {
    rules: [
      // 用Babel转译ES6+代码，兼容低版本浏览器
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: ['@babel/preset-env']
          }
        }
      },
      // 处理CSS文件：自动加载并注入到页面中
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader']
      }
    ]
  },
  // 生成source map，方便开发时调试源码
  devtool: 'source-map'
};

3. 编写主入口文件（./resources/app.js） #

现在你不用再手动引入jQuery和hljs的外部脚本了，直接在app.js里组织业务逻辑，Webpack会自动帮你打包所有依赖：

// 引入highlight.js的样式（Webpack会自动处理CSS资源）
import 'highlight.js/styles/github.css';
import hljs from 'highlight.js';

// 初始化代码高亮功能
hljs.highlightAll();

// 引入你的自定义模块（比如回到顶部组件）
import './return-to-top.js';

// 直接使用jQuery（ProvidePlugin已经全局注入）
$(document).ready(function() {
  console.log('jQuery已成功加载！');
  // 在这里写你的业务逻辑，比如绑定事件、操作DOM
});

4. 编写自定义模块（return-to-top.js） #

作为独立的功能模块，你可以直接使用$，无需额外导入：

// 回到顶部按钮的实现逻辑
$(function() {
  const $returnTop = $('<button class="return-to-top">↑</button>').appendTo('body');
  
  // 默认隐藏按钮
  $returnTop.hide();
  
  // 监听滚动事件，控制按钮显示/隐藏
  $(window).scroll(function() {
    $(this).scrollTop() > 300 ? $returnTop.fadeIn() : $returnTop.fadeOut();
  });
  
  // 点击按钮平滑回到顶部
  $returnTop.click(function() {
    $('html, body').animate({ scrollTop: 0 }, 300);
  });
});

5. 在PHP页面引入打包后的资源 #

最后，在你的PHP模板或页面底部，只需要引入Webpack打包好的bundle.js即可：

<!-- 建议放在页面底部，确保DOM加载完成后执行JS -->
<script src="/assets/bundle.js"></script>

额外实用小提示 #

• 开发时执行npm run dev，Webpack会实时监听文件修改并自动重新打包，不用手动刷新页面
• 如果有其他依赖jQuery的插件，直接用npm install xxx安装，然后在app.js里import 'xxx'即可，Webpack会自动处理依赖关系
• 若遇到老旧插件不支持模块导入的情况，webpack.ProvidePlugin基本能覆盖大部分场景，特殊情况可以尝试exports-loader适配

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