EP051. “JavaScript 构建工具入门：npm + @wordpress/scripts”

首页 › WordPress 开发课程 › JAVASCRIPT 入门 · EP051

约 14 分钟· #EP051#JAVASCRIPT 入门

📌 代码对照说明：这一讲对应的代码资料夹是 sources/Section 11/41-existing-2021/41-end，但这个资料夹是 EP051～EP055（Section 11 后半到 Section 12 Google Maps）共用的一个「累积快照」，里面已经包含了后面几讲才会写的内容（例如 functions.php 里 Section 12 才会讲的 add_filter('acf/fields/google_map/api', 'universityMapKey')，以及 src/index.js 里已经 import 了后面讲座会用到的 MobileMenu / HeroSlider 模块）。这篇笔记只提取跟 EP051 本身（引入 npm 构建工具）有关的部分，Google Maps 相关代码不属于这一讲，不在这里出现。

课程到这里为止一直只写 PHP，这一讲开始要写 JavaScript 了。Brad 借这个机会先讲清楚一个前提： 现代前端开发基本都要靠「构建工具」把零散的 JS/SCSS 源码文件编译打包成浏览器能直接加载的单一文件 （连 WordPress 官方默认主题的 package.json 都证明了这不是个人偏好，是行业标准）。这门课选用 WordPress 官方维护的 @wordpress/scripts（简称 wp-scripts），配置几乎为零，很好上手。这一讲的目标很简单：把 Node.js 装好，把 package.json 放进主题文件夹，跑 npm install 装依赖，再用 npm run start 跑一次「改代码自动重新打包」的完整流程，确认整套工具链能正常工作。

涉及文件

wp-content/themes/fictional-university-theme/package.json （新建，从 university-static 仓库
复制过来，是这个 JS 项目的「依赖清单 + 可执行脚本」配置文件）
wp-content/themes/fictional-university-theme/node_modules/ （新建，运行 npm install 后自动生成，
存放下载下来的依赖包本体，不需要手动创建也不需要打包/进版本控制）
wp-content/themes/fictional-university-theme/src/index.js （已存在的文件——src/build/css/
images 这些资料夹其实从 EP015 整合静态站时就已经跟着 university-static 项目一起复制进主题了，
只是当时只是拿现成编译好的 build 产出用，没人在本地真正跑过 npm 工具链。这一讲只是临时在
src/index.js 末尾加一行 alert() 测试代码，验证保存文件后 build 产出会不会自动重新编译，
测试完就应该删掉，不是要保留的正式代码）

代码实现

package.json（新建，直接从 university-static 仓库拿来用，不用自己手写）：

{
  "name": "fictional-university-theme",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start",
    "dev": "wp-scripts start",
    "devFast": "wp-scripts start",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@glidejs/glide": "^3.4.1",
    "@wordpress/scripts": "*",
    "axios": "^0.21.1",
    "normalize.css": "^8.0.1"
  }
}

要点：

dependencies 就是这个项目要用到的「配料表」：@wordpress/scripts 是打包工具本身；
@glidejs/glide 是首页轮播动画用的库；normalize.css 是统一各浏览器默认间距的 CSS reset；
axios 是后面章节做网络请求（AJAX）会用到的库，这一讲还用不到。
scripts 里的 start 和 build 是可以用 npm run 直接执行的命令，这两个是 transcript 里
实际讲解的。dev/devFast（跟 start做的事一样）和 test（npm 项目模板自带的占位脚本，
没实际测试逻辑）这几个是 package.json 文件里本来就有的，transcript 没有单独讲解，
这里照实贴出来但不额外展开。

命令行操作（不是要贴进文件的代码，是终端里依次要跑的命令）：

# 1. 确认 Node.js 装好了（先去 nodejs.org 下载安装，LTS 版或最新版都可以）
node --version

# 2. 命令行切到主题文件夹（VS Code 里按 Ctrl+J / Cmd+J 打开内建终端，
#    只要侧边栏项目指向的就是这个主题文件夹，终端会自动停在同一个目录）
npm install

# 3. 持续监听模式：改一次文件就自动重新打包一次，会一直挂在后台运行
npm run start
# 按 Ctrl+C（Mac 是 Command+C）才能停止

# 4. 只打包一次就结束，不会持续监听（用得比 start 少很多）
npm run build

临时测试用的改动（验证完流程就应该还原，不是正式代码）：

// wp-content/themes/fictional-university-theme/src/index.js
// 只是临时加来测试用，验证保存后 build 产出会自动重新编译
alert("just a test");

保存后命令行会看到 npm run start 重新打包的输出，刷新前台网站就能看到这个弹窗。

[截图：浏览器前台刷新后弹出的 alert("just a test") 测试弹窗，证明 npm run start 的自动编译流程接通了]

同样地， transcript 里也临时改了 css/modules/headline.scss 里某个规则的文字颜色（改成黄色）来验证 SCSS 也会被一起编译进 build 里，测试完同样要改回去，这两处都只是「证明工具链在跑」的一次性动作，不是这一讲要求写死的功能代码，所以这份笔记不把它们当正式代码来贴。

Hook / Function 速查

名称	类型	用途
`package.json`	Node 项目配置文件（约定命名）	声明项目依赖（`dependencies`）和可执行脚本（`scripts`），`npm install` 靠它知道要装什么
`npm install`	npm 命令行命令	读取 `package.json`，下载安装所有依赖，生成 `node_modules` 文件夹
`npm run start`	npm 命令行命令	持续在后台监听 `src` 里文件的改动，自动重新编译打包到 `build` 文件夹，直到手动 Ctrl+C 停止
`npm run build`	npm 命令行命令	跟 `start` 做同样的编译打包，但只执行一次就结束，不会持续监听
`@wordpress/scripts`	npm 包（WordPress 官方维护）	零配置的 JS/SCSS 编译打包工具，本课程后面所有 JS 内容都靠它编译成浏览器能读的文件
`src/index.js`	约定文件路径（`@wordpress/scripts` 强制要求）	打包工具认的入口文件，必须放在名字精确为 `src` 的资料夹里，文件名必须精确是 `index.js`

常见坑

没装 Node.js 就直接跑 npm 相关命令，命令行会提示 command not found 或 unknown command，
需要先去 nodejs.org 下载安装，装完如果还是不认，试着重启电脑或重启文本编辑器。
src 资料夹名字、index.js 文件名必须完全精确（不能改名字），工具是按这两个精确名字去找入口文件的。
build 文件夹里的文件（比如 build/index.js）是给浏览器读的编译产出，不是给人读的，**绝对不要
手动去编辑它，所有真正要写的代码都写在 src 文件夹里**。
npm run start 会一直挂在后台监听，要点一下命令行让它获得焦点，再按 Ctrl+C（Mac 是 Command+C）
才能真正停止，不是把终端窗口关掉就算数。
每一讲末尾下载的资源 zip 里不包含 node_modules 文件夹（体积太大），**拿到项目后要自己重新跑一次
npm install 补回来**，不需要也不应该把 node_modules 存进版本控制。

延伸 / 后续讲座会用到

往后整个 Section 11 以及后面 Section 12（Google Maps 互动地图）、Section 13-14（Live Search AJAX）等章节的 JavaScript 代码都会写在 src/index.js 和 src/modules/ 底下，靠这一讲装好的 npm run start 自动编译进 build 文件夹。这次拿到的代码快照里 src/modules/ 已经有 MobileMenu.js、HeroSlider.js、GoogleMap.js 等模块文件，但这些是后面讲座各自的内容，不属于这一讲。

Sources

Udemy：

Become a WordPress Developer: Unlocking Power With Code — Section 11, EP051