nwb Preact 应用开发工作流指南:从依赖安装、热更新开发到测试与构建

原创2026-10-11 23:18:372,000 阅读
文章标签:开发工具前端构建

nwb Preact 应用开发工作流指南:从依赖安装、热更新开发到测试与构建

本文以 nwb 仓库中 preact-app 项目模板的 CONTRIBUTING.md 为主线,结合仓库源码(命令实现、测试与构建链路、Karma 配置)展开,系统讲解一个由 nwb 生成的 Preact 应用在日常开发中的完整工作流:环境准备、依赖安装、开发服务器(热模块替换)、单元测试(含覆盖率与监听模式)、生产/开发构建以及清理产物。读完本文,你将掌握每个 npm 脚本背后的 nwb 命令、底层执行链路与可调参数,能够在新生成的 Preact 应用中直接上手开发、测试与发布构建。

前置条件:Node.js 环境

模板 CONTRIBUTING.md 明确要求:

  • 必须安装 Node.js >= 10。

nwb 本身通过 nwb 命令行驱动 Webpack、Karma、Babel 等工具链,这些工具都运行在 Node.js 之上,因此较新且稳定的 LTS 版本 Node.js 是唯一硬性前提。此外,nwb 项目创建时会自动执行 git init 并提交初始 commit(除非传入 --no-git,见 createProject.js),所以本机装有 Git 也会让后续版本管理更顺畅。

安装依赖:npm install

在应用根目录执行:

npm install

该命令会读取生成项目中的 package.json 安装全部开发依赖。生成模板的包清单位于 templates/preact-app/_package.json,其中把 nwb 本身作为 devDependency 写入(版本号为创建项目时 nwb 的当前版本),并把全部开发命令预置为 npm scripts:

{
  "scripts": {
    "build": "nwb build-preact-app",
    "clean": "nwb clean-app",
    "start": "nwb serve-preact-app",
    "test": "nwb test-preact",
    "test:coverage": "nwb test-preact --coverage",
    "test:watch": "nwb test-preact --server"
  },
  "devDependencies": {
    "nwb": "{{nwbVersion}}"
  }
}

模板中的 {{name}}、{{nwbVersion}} 会在 nwb new preact-app <name> 或 nwb init preact-app 创建项目时由 createProject.js 通过模板渲染替换为真实项目名与 nwb 版本。

注:nwb 在运行 build、serve、test 等命令时会校验“正在运行的 nwb 版本”与项目 package.json 中声明的 nwb 版本是否匹配(semver 满足),不满足会直接报错并终止,见 cli.js。这也是把 nwb 作为本地 devDependency 安装的意义所在。

开发服务器:npm start

执行:

npm start

nwb 会启动 Webpack 开发服务器,应用运行在 http://localhost:3000,并默认开启 Hot Module Replacement(热模块替换,HMR)——修改代码保存后页面自动更新,无需手动刷新。

背后的命令与源码链路

npm start 实际执行 nwb serve-preact-app(入口 serve-preact-app.js),它调用通用 serve()(appCommands.js)生成开发配置并交给 Webpack 开发服务器。默认端口来自 constants.js 的 DEFAULT_PORT = process.env.PORT || 3000,因此你也可以通过环境变量改变端口:

PORT=8080 npm start

模板应用入口 templates/preact-app/src/index.js 展示了 HMR 的标准写法:在 module.hot 存在时 module.hot.accept('./App', init),从而在 App 模块变更后自动重新渲染。应用被渲染进 #app 这个 DOM 节点。

Preact 专属配置:兼容层与渲染 Shimming

Preact 项目配置定义在 src/preact/index.js,其中将 react 与 react-dom 都 alias 到 preact/compat,并把 react-dom/test-utils alias 到 preact/test-utils,这意味着在 Preact 应用中可以直接 import 兼容 React 的第三方组件。JSX 编译则由 src/preact/preact-preset.js 指定 pragma: 'h'、pragmaFrag: 'Fragment'。

此外,nwb 为 Preact 提供了渲染 Shim(src/preact/renderShim.js):开发环境下自动 require('preact/debug') 启用 Preact Devtools,并把入口模块导出内容挂载到 NWB_QUICK_MOUNT_ID(默认 app)对应的 DOM 节点上,同时处理顶层 HMR 的重新渲染。

运行测试

生成项目提供三个测试相关脚本:

npm test              # 运行一次测试
npm run test:coverage # 运行测试并生成覆盖率报告到 coverage/
npm run test:watch    # 监听文件变化,每次变更自动重跑测试

三者分别对应:

  • nwb test-preact
  • nwb test-preact --coverage
  • nwb test-preact --server

测试执行链路与默认配置

nwb test-preact(test-preact.js)调用 karmaServer.js,它会强制 NODE_ENV=test,再基于项目类型配置生成 Karma 配置并启动 Karma Server。默认行为(见 createKarmaConfig.js)包括:

  • 浏览器:ChromeHeadless(无头 Chrome);
  • 测试框架:mocha + webpack(测试文件同样经 Webpack 编译打包);
  • 测试文件匹配:默认匹配 +(src|test?(s))/**/*+(.spec|.test).js,即 src/ 或 tests/ 下所有 .spec.js / .test.js(也支持与源码同目录的 __tests__ 目录,覆盖率计算默认排除 test/、tests/、src/**/__tests__/)。

模板自带的示例测试 templates/preact-app/tests/App.test.js 使用 expect 断言库与 preact 的 render() 把 <App/> 渲染进临时 DOM 节点,再断言文本内容,可直接作为编写组件测试的范式。

覆盖率报告

--coverage 会在 createKarmaConfig.js 中启用 babel-plugin-istanbul 插桩,并将报告输出到项目根目录的 coverage/,同时生成:

  • coverage/html(HTML 报告)
  • coverage/lcovonly(lcov 格式)
  • text-summary(终端摘要)

另外,在 CI 环境(设置了 CI 或 CONTINUOUS_INTEGRATION 环境变量)下运行测试会自动强制开启覆盖率并单次运行(singleRun: true);普通本地运行则取决于是否传入 --server——--server 会让 Karma 持续监听并重跑,这正是 test:watch 的原理。

构建:npm run build

npm run build

默认创建 生产构建,产物输出到应用根目录的 dist/。若需要 开发构建,在运行命令时设置 NODE_ENV 环境变量为 development:

NODE_ENV=development npm run build

构建链路与产物细节

npm run build 实际执行 nwb build-preact-app(build-preact-app.js),通用构建逻辑见 appCommands.js:它会先执行 clean-app 清理旧产物,再调用 Webpack 编译。若 NODE_ENV 未设置,webpackBuild.js 会将其默认置为 production,这也解释了为什么 npm run build 默认就是生产构建。

产物命名规则在 appCommands.js 中定义:

  • 生产构建:[name].[chunkhash:8].js(带 8 位内容哈希,利于长期缓存);
  • 开发构建:[name].js(无哈希)。

构建配置还包含以下默认行为:

  • Babel 目标:生产环境默认 targets 为 >0.2%, not dead, not op_mini all(见 constants.js),即面向主流现代浏览器做 ES5 转译与 polyfill;
  • HTML 模板:使用项目 src/index.html(若存在),否则回退到内置模板(lang、mountId: 'app'、title 取 package.json 的 name,见 appCommands.js);
  • public 目录拷贝:若项目根目录存在 public/,其中的静态资源会被原样复制到构建产物(模板 templates/preact-app/public/ 仅含 .gitkeep 占位);
  • vendor 拆分:默认会把来自 node_modules/ 的模块拆分为独立的 vendor bundle(可用 --no-vendor 关闭)。

清理构建产物:npm run clean

npm run clean

对应命令为 nwb clean-app(clean-app.js),默认删除 coverage/ 与 dist/ 两个目录(也支持 nwb clean-app <a href="https://link.gitcode.com/i/7a24e75f664d10ba3cf5af1f670e904b" target="_blank">dist_dir] 指定要清理的输出目录)。生成项目的 [_.gitignore 也恰好忽略了 /coverage、/dist 与 /node_modules,保证这些生成物不会进入版本库。

项目类型标识:nwb.config.js

生成项目根目录自带一个 nwb.config.js:

module.exports = {
  type: 'preact-app'
}

type: 'preact-app' 用于让通用命令(nwb serve、nwb build、nwb test)自动识别项目类型并分派到对应的 Preact 命令——分派逻辑见 serve.js 与 build.js 中的 SERVE_COMMANDS / BUILD_COMMANDS 映射表。换言之,即便不写死 nwb serve-preact-app,在项目内直接运行 nwb serve 也能得到完全相同的行为。

工作流速查

阶段 命令 底层 nwb 命令 说明
安装 npm install — 安装全部依赖(含本地 nwb)
开发 npm start nwb serve-preact-app 开发服务器 @ http://localhost:3000,支持 HMR
测试 npm test nwb test-preact Karma + Mocha + Webpack,ChromeHeadless 运行一次
覆盖率 npm run test:coverage nwb test-preact --coverage 生成报告到 coverage/
监听测试 npm run test:watch nwb test-preact --server 文件变更自动重跑
构建 npm run build nwb build-preact-app 默认生产构建,产物在 dist/
开发构建 NODE_ENV=development npm run build 同上 无哈希文件名,便于调试
清理 npm run clean nwb clean-app 删除 coverage/ 与 dist/

这套工作流覆盖了从拿到新生成的 nwb Preact 应用到完成一次可发布构建的全部环节。理解每个脚本背后的 nwb 命令与配置默认值(端口、测试匹配规则、覆盖率输出、构建哈希、浏览器目标等),可以让你在需要时用 --port、--config、--plugins 等参数或修改 nwb.config.js 平滑地定制开发体验,而无需手写任何 Webpack / Karma 配置。

登录后查看全文
nwb