nwb Inferno App 项目开发手册:安装、热更新、测试与构建全流程

原创2026-10-11 23:16:431,876 阅读
文章标签:开发工具前端构建

nwb Inferno App 项目开发手册:安装、热更新、测试与构建全流程

本指南基于 nwb 项目模板 templates/inferno-app 自带的 CONTRIBUTING.md,面向通过 nwb new inferno-app 生成的 Inferno 应用项目,系统讲解从环境准备、依赖安装、开发服务器、单元测试到生产构建的完整日常开发工作流。读完本文,你将掌握该模板内置的每一条 npm 脚本背后的 nwb 命令、它们在源码中的真实调用链,以及如何通过环境变量和命令行参数调整开发与构建行为。

前置条件:Node.js 版本要求

模板的 CONTRIBUTING.md 首先明确了一个硬性要求:

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

nwb 本身通过 npm 分发并驱动 Webpack、Karma 等工具链,因此除 Node.js 外还需要随 Node.js 一起安装的 npm。该版本要求与模板中 _.travis.yml 的 CI 配置一致——它指定在 Node.js 10 环境下运行测试:

language: node_js
node_js:
  - 10

在实际开发环境中,可以通过 node -v 与 npm -v 先确认版本满足要求。

安装开发依赖

在项目根目录执行:

npm install

这一条命令会安装开发所需的全部依赖。它之所以如此简单,是因为项目骨架在生成时已经写好了 package.json(模板源文件为 _package.json),其中预置了与 nwb 命令一一对应的 npm scripts:

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

说明两点:

  • devDependencies 中只声明了 nwb 本体;Inferno 运行时依赖由 nwb 在创建项目时按需安装进 dependencies。从 createProject.js 的 createAppProject() 可以看到,模板复制完成后会调用 install(dependencies, {cwd: targetDir, save: true}, cb),其中 dependencies 来自 Inferno 项目配置 src/inferno/index.js 的 getProjectDependencies()——默认是 ['inferno'],若创建时确认启用 inferno-compat,还会追加 inferno-compat、inferno-clone-vnode、inferno-create-class、inferno-create-element。
  • 若想指定 Inferno 的具体版本,可以在创建项目时使用 --inferno 选项,例如 nwb new inferno-app my-app --inferno=7.x(参见 docs/Commands.md 的 Inferno app options 一节)。

启动开发服务器(npm start)

npm start

该脚本实际执行 nwb serve-inferno-app,启动带 Hot Module Replacement(HMR)热模块替换的开发服务器,默认地址为:

http://localhost:3000

默认端口与参数覆盖

默认端口 3000 定义在 src/constants.js:

export const DEFAULT_PORT = process.env.PORT || 3000

即也可以通过 PORT 环境变量改变端口。此外 nwb serve-inferno-app 还支持常用参数(完整列表见 docs/Commands.md):

  • --port <port>:指定开发服务器端口
  • --host <host>:修改开发服务器绑定的主机名
  • --no-clear:不在编译结果展示前清空控制台
  • --no-fallback:关闭对任意路径回退提供 index.html 的行为(供使用 HTML5 History API 的应用使用)
  • --reload:当热更新请求未被接受时自动刷新页面

向 npm 脚本传递额外参数时需要先写 --,例如:

npm start -- --port 8080

源码视角:命令调用链

nwb serve-inferno-app 的入口实现位于 src/commands/serve-inferno-app.js:

export default function serveInferno(args, cb) {
  serve(args, infernoConfig(args), cb)
}

它把 inferno 的配置对象交给 src/appCommands.js 中的通用 serve(),后者依次完成:

  1. createServeConfig() 生成默认开发配置:入口默认为 src/index.js,输出到 dist/,通过 src/index.html 生成 HTML 页面;
  2. webpackServer()(见 src/webpackServer.js)将 NODE_ENV 默认为 development,探测端口可用性(端口被占用时会交互式询问是否改用其他端口),随后启动 Webpack 开发服务器。

HMR 如何在模板中生效

模板入口 src/index.js 自身完成了渲染与热更新接管的样板代码:

import './index.css'

import {render} from 'inferno'

import App from './App'

render(<App/>, document.querySelector('#app'))

if (module.hot) {
  module.hot.accept()
}

对应的 src/index.html 提供了挂载点 <div id="app"></div>;修改 src/App.js 并保存即可触发热更新。

Inferno 开发构建与 React 兼容

src/inferno/index.js 中还有两个对开发体验至关重要的配置:

  • 开发版本替换:Inferno 默认的模块构建是生产版本,nwb 在 NODE_ENV !== 'production'(即开发与测试)时,会将 inferno 别名为 inferno/dist/index.dev.esm.js,保证开发服务器与测试运行的是带开发警告的版本;
  • React 兼容层:通过 Webpack alias 将 react 与 react-dom 指向 inferno-compat,因此在 Inferno 应用中可以直接复用兼容的 React 模块。

同时,src/inferno/inferno-preset.js 提供了 Babel 预置,包含 @babel/plugin-syntax-jsx 与 babel-plugin-inferno,确保 JSX 语法能被正确编译为 Inferno 的 VNode。

运行测试

模板提供三条测试脚本:

# 运行一次测试
npm test

# 运行测试并生成覆盖率报告(输出到 coverage/)
npm run test:coverage

# 监听变化,每次变更自动重跑测试
npm run test:watch

底层机制

三条脚本最终都落到 nwb test-inferno,实现位于 src/commands/test-inferno.js:

export default function testInferno(args, cb) {
  karmaServer(args, infernoConfig(args).getKarmaTestConfig(), cb)
}

其核心是 Karma 测试服务器(见 src/karmaServer.js),启动前会强制 process.env.NODE_ENV = 'test',并基于 createKarmaConfig() 生成的配置运行浏览器内单元测试。三个脚本与 nwb 参数的对应关系为:

  • npm test → nwb test-inferno(运行一次)
  • npm run test:coverage → nwb test-inferno --coverage(在 coverage/ 生成覆盖率报告)
  • npm run test:watch → nwb test-inferno --server(保持 Karma 服务器运行,每次变更重跑测试)

其中 --coverage 与 --server 是 nwb test 系列命令的标准选项,说明见 docs/Commands.md。

模板测试示例

模板自带一个针对 App 组件的冒烟测试 tests/App.test.js,使用 mocha(tests/.eslintrc 中已声明 mocha 环境)与 expect 断言库:

import expect from 'expect'
import {render} from 'inferno'

import App from 'src/App'

describe('App component', () => {
  let node

  beforeEach(() => {
    node = document.createElement('div')
  })

  afterEach(() => {
    render(null, node)
  })

  it('displays a welcome message', () => {
    render(<App/>, node)
    expect(node.textContent).toContain('Welcome to Inferno')
  })
})

注意它使用 import App from 'src/App' 这种基于 src/ 目录的模块解析,nwb 已内置相关 Webpack 配置。nwb 的集成测试 tests/commands/test-test.js 也覆盖了 nwb new inferno-app 之后直接运行 nwb test 的成功场景,可作为“模板开箱即可测试”的佐证。

将覆盖率接入 CI

模板的 .travis.yml 展示了把 coverage/ 下的 lcov.info 上传到 codecov.io 与 Coveralls 的常见做法,同时 .gitignore 已默认忽略 coverage、dist 与 node_modules:

/coverage
/dist
/node_modules
npm-debug.log*

创建构建

npm run build

该脚本执行 nwb build-inferno-app,默认创建生产构建,输出到 dist/ 目录。从 src/webpackBuild.js 可以看到,构建命令在未显式设置时会把 NODE_ENV 默认为 production:

if (!process.env.NODE_ENV) {
  process.env.NODE_ENV = 'production'
}

创建开发构建

如需开发构建,在运行该命令时把 NODE_ENV 环境变量设为 development:

# *nix
NODE_ENV=development npm run build

# Windows (cmd)
set NODE_ENV=development&& npm run build

开发构建与生产构建的差异在 src/appCommands.js 的 createBuildConfig() 中有直接体现:生产模式下产物文件名带内容哈希 [name].[chunkhash:8].js,便于长期缓存;开发模式下则是不带哈希的 [name].js。

构建行为要点

  • 默认入口与输出:入口默认为 src/index.js,输出目录默认为 dist/;也可直接执行 nwb build-inferno-app <entry> <dist_dir> 自定义。
  • vendor 分包:从 node_modules/ 导入的依赖会默认拆分为独立的 vendor.js / vendor.css 包,可用 --no-vendor 关闭。
  • HTML 生成:构建会附带生成 HTML 页面(默认使用 src/index.html),可用 --no-html 关闭。
  • 传参语法:经 npm 脚本传递构建参数同样需要 -- 分隔,例如 npm run build -- --no-vendor。
  • 构建前自动清理:build() 任务序列会先执行 clean-app 清理旧的 dist/ 输出,再执行 Webpack 编译,保证产物目录干净。

清理构建产物

npm run clean

该脚本执行 nwb clean-app,其实现见 src/commands/clean-app.js:

export default function cleanApp(args, cb) {
  let dist = args._[1] || 'dist'
  clean('app', ['coverage', dist], cb)
}

它会删除 dist/(默认输出目录,也可通过参数指定其他目录)以及 coverage/。底层的 clean() 工具(见 src/utils.js)会先检查目录是否存在,再通过 spinner 提示删除进度,因此即使目录不存在也不会报错。需要提醒的是:clean 是破坏性操作,执行后构建产物与覆盖率报告将被删除,如需保留请先做好备份。

配置文件与其他约定

nwb.config.js

模板自带 nwb.config.js,内容极简:

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

由于 npm scripts 已经使用了项目类型专属命令(serve-inferno-app、build-inferno-app 等),这份配置文件仅在需要自定义 Webpack、Babel 等行为时才必要——正如 docs/Commands.md 所述,“骨架项目自带的 nwb.config.js 在不需要配置时可以直接删除”。若需要配置,可参考 docs/Configuration.md。

通用命令也可用

由于 nwb.config.js 已声明项目类型,你同样可以使用通用命令 nwb serve、nwb build、nwb test、nwb clean 完成上述全部工作,效果与项目类型专属命令一致。

快速开发替代方案

对于从单个 .js 文件起步、临时验证 Inferno 代码的快速场景,nwb 还提供 nwb inferno run <entry.js>(开发服务器)与 nwb inferno build <entry.js> <a href="https://link.gitcode.com/i/261f71b61dca1ff7943dfb27023b11c5" target="_blank">dist_dir](生产构建)两条快速开发命令,详见 [docs/guides/QuickDevelopment.md。它们与本模板的完整项目工作流互补:前者零配置即用,后者面向正式项目维护。

小结

nwb 生成的 Inferno App 项目把日常开发收敛为五条 npm 脚本:npm start 提供带 HMR 的开发服务器,npm test / npm run test:coverage / npm run test:watch 覆盖单次测试、覆盖率与监听模式,npm run build 产出生产构建(NODE_ENV=development 时产出开发构建),npm run clean 一键清理 dist/ 与 coverage/。结合 templates/inferno-app 模板目录与 src 源码中 serve-inferno-app、test-inferno、build-inferno-app、clean-app 四条命令的实现,可以清晰看到每一条脚本背后的完整工具链,从而在需要自定义行为时准确找到切入点。

登录后查看全文
nwb