nwb Inferno App 项目开发手册:安装、热更新、测试与构建全流程
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(),后者依次完成:
createServeConfig()生成默认开发配置:入口默认为src/index.js,输出到dist/,通过src/index.html生成 HTML 页面;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 四条命令的实现,可以清晰看到每一条脚本背后的完整工具链,从而在需要自定义行为时准确找到切入点。