nwb 常见问题实战指南：配置检视、CSS Modules、构建瘦身与 VS Code 调试

• 开发工具
• 前端构建

本文是一份基于 nwb 官方 FAQ（docs/FAQ.md）整理并对照仓库源码深化的实战指南。nwb 是一个面向 React、Preact、Inferno 与原生 JS 应用及 npm 模块的零配置构建工具，本文聚焦开发者日常使用中最高频的 6 类问题：如何检视 nwb 生成的配置、如何开启 CSS Modules、如何通过 cherry-picking 减小 bundle 体积、如何复制非 JavaScript 文件、如何避免控制台被清屏，以及如何在 VS Code 中调试开发服务器与 Karma 测试。读完本文，你将掌握这些问题的标准解法、对应配置项的真实语义与源码级依据，可以直接迁移到自己的 nwb 项目中。

nwb 名字的由来：N + W + B，为易键入而设计

FAQ 中对“nwb 代表什么”给出了一个朴素而明确的回答：短小易键入。nwb 使用Node.js、Webpack 和Babel 来构建面向 Web 的应用（apps for the web）与面向 npm 的模块（modules for npm），这四个字母恰好覆盖了工具链的三层核心：

• Node.js：nwb 本身是运行在 Node.js 环境下的 CLI 工具，所有命令（nwb build、nwb serve、nwb test等）都由 Node 执行；
• Webpack：应用类项目的打包、开发服务器与生产构建均由 Webpack 驱动（见 createWebpackConfig.js 与 createServerWebpackConfig.js）；
• Babel：无论是应用还是模块，ES 语法转译都由 nwb 生成的 Babel 配置完成（见 createBabelConfig.js）。

nwb这个名字正是在这些含义的组合中挑选出来、读起来顺口且极易键入的缩写。这一设计哲学与 nwb 整体“零配置起步，需要时再配置”的产品定位一脉相承。

检视 nwb 生成的配置：DEBUG 环境变量与 --no-clear

nwb 的默认配置可以让你开箱即用地开发、测试和构建，但当你需要调优时，第一步往往是想知道 nwb 到底生成了什么样的 Babel、Webpack、Karma 配置。

开启 DEBUG 输出

在运行命令前设置DEBUG环境变量为nwb，即可在控制台打印 nwb 生成的各类配置：

# *nix export DEBUG=nwb # Windows set DEBUG=nwb

这一机制在源码中有直接对应：nwb 通过著名的debug库创建了一个命名空间为nwb的调试器（见 src/debug.js）：

import debug from 'debug' export default debug('nwb')

随后，各配置生成模块会通过这个调试器输出关键中间产物，例如：

• 用户配置处理完成后打印合并结果：debug('user config: %s', deepToString(userConfig))（见 src/config/user.js）；
• Webpack 服务器配置打印完整 webpack config：debug('webpack config: %s', deepToString(webpackConfig))（见 src/webpackServer.js）；
• Karma 配置打印完整 karma config：debug('karma config: %s', deepToString(karmaConfig))（见 src/createKarmaConfig.js）；
• 模块构建时打印 Babel 配置：debug('babel config: %s', deepToString(babelConfig))（见 src/moduleBuild.js）。

设置DEBUG=nwb后，这些配置会以可读形式输出到终端，便于你确认 loader 链、插件列表、入口与输出路径是否符合预期。

防止控制台被清屏：--no-clear

开发服务器在显示构建状态前会主动清空控制台（见 src/WebpackStatusPlugin.js 中的clearConsole()），这会导致你无法回看之前的日志。如果你希望保留滚动记录以便排查意外错误，可以给服务类命令传入--no-clear标志：

# 通过 npm scripts 运行 nwb 时 npm start -- --no-clear # 直接运行 nwb serve 时 nwb serve --no-clear

源码层面的逻辑很直观：--no-clear对应args.clear === false，当它被传入时，nwb 既不会在启动前清屏（见 src/webpackServer.js），也会禁用构建状态插件对控制台的清屏动作（见 src/webpackServer.js）。此外，--no-clear还会让端口占用时的交互提示不再清屏（见 src/webpackServer.js）。该选项在 CLI 帮助中同样有说明：--no-clear don't clear the console when displaying build status（见 src/cli.js）。

开启 CSS Modules：webpack.rules 与 localIdentName

nwb 默认的样式表规则由css-loader、postcss-loader（内置 Autoprefixer）以及开发模式下的style-loader链式组成（详见 docs/Stylesheets.md）。开启 CSS Modules 的标准做法是通过nwb.config.js中的webpack.rules直接给默认样式规则里的css-loader传入modules与localIdentName选项：

module.exports = { webpack: { rules: { css: { modules: true, localIdentName: ( process.env.NODE_ENV === 'production' ? '[path][name]-[local]-[hash:base64:5]' : '[hash:base64:5]' ) } } } }

这里css是 nwb 生成的默认 CSS 规则中css-loader 的 loader id。按 docs/Stylesheets.md 的说明，默认css-rule由以下 loader 链构成：

上面的localIdentName表达式是 FAQ 推荐的生产环境与开发环境差异化命名：生产构建使用[path][name]-[local]-[hash:base64:5]以保留可读性并附带哈希，开发构建使用更短的[hash:base64:5]以减小类名长度。

只对部分样式启用 CSS Modules

如果你只需要对一部分样式表启用 CSS Modules，则不应修改默认规则，而应配置 自定义样式表规则（webpack.styles）。例如为src/components目录启用 CSS Modules、其余 CSS 走普通规则：

module.exports = { webpack: { styles: { css: [ // 对 src/components 下的 CSS 启用 CSS Modules { include: path.resolve('src/components'), css: { modules: true, localIdentName: ( process.env.NODE_ENV === 'production' ? '[path][name]-[local]-[hash:base64:5]' : '[hash:base64:5]' ) } }, // 兜底规则：处理其余所有 CSS { exclude: path.resolve('src/components') } ] } } }

需要说明的是：自定义样式规则要求webpack.styles的值是对象，且属性名只能是css（普通 CSS）或已安装的 CSS 预处理器插件名（如使用nwb-sass时为sass）。nwb 的配置校验器会逐项检查并报错（见 src/config/webpack.js）。如果你完全不想让 nwb 管理样式规则，可以设webpack.styles: false。

减小 bundle 体积：为解构导入启用 cherry-picking

如果你使用解构导入（destructuring imports）来引用 React Router、React Bootstrap 这类库：

import {Button} from 'react-bootstrap'

那么打包时会把整个库都打进 bundle，而不是只包含你实际用到的部分。nwb 提供的解决方案是配置babel.cherryPick（见 docs/Configuration.md），把这类解构导入在编译期改写为对子模块的单独导入。

配置方式

module.exports = { babel: { cherryPick: 'react-bootstrap' } }

cherryPick接受一个字符串或字符串数组，用于列出需要应用 cherry-picking 转换的模块名。其底层实现基于babel-plugin-lodash：上面的配置会把

import {Button, FormGroup} from 'react-bootstrap'

等价转换为类似

import Button from 'react-bootstrap/lib/Button' import FormGroup from 'react-bootstrap/lib/FormGroup'

的效果，从而只打包实际引用的子模块。注意该特性仅对import语法生效。

从源码看，nwb 会在处理 Babel 配置时对cherryPick做类型校验，仅接受String或Array，否则报错（见 src/config/babel.js）。仓库的测试夹具中也提供了一个可直接对照的真实示例——tests/fixtures/projects/cherry-pick/nwb.config.js：

module.exports = { type: 'react-component', babel: { cherryPick: 'react-bootstrap' } }

该夹具项目的依赖声明里包含react-bootstrap（见 tests/fixtures/projects/cherry-pick/_package.json），可用于在测试环境中验证解构导入被正确改写、最终 bundle 只包含被用到的模块。

使用注意事项

babel-plugin-lodash并非对所有模块都兼容。FAQ 建议：在使用cherryPick前，先查阅该插件 issues 中关于目标模块兼容性的已知问题，并把你发现的新问题反馈上去。也就是说，cherryPick更适合导出结构规整、每个子模块独立可导入的库。

构建 React 组件/库时复制非 JavaScript 文件：--copy-files

当你用nwb build-react-component（或build-web-module）构建模块时，默认只转译src/下能被 Babel 处理的 JavaScript 文件。如果你还有 CSS、JSON 等其他类型的文件需要原样复制到构建输出目录（如lib/、es/），请传入--copy-files标志：

nwb build-react-component --copy-files

这一行为的源码实现非常直接：moduleBuild从命令行参数中读取--copy-files，并把它转换为 Babel CLI 的--copy-files --no-copy-ignored参数（见 src/moduleBuild.js）：

let babelCliOptions = { copyFiles: !!args['copy-files'], src: path.resolve('src'), }

if (copyFiles) { args.push('--copy-files', '--no-copy-ignored') }

在 CLI 帮助中，该选项的说明是：--copy-files copy files which won't be transpiled by Babel (e.g. CSS)（见 src/cli.js）。换句话说，--copy-files会复制那些不会被 Babel 转译的文件（如 CSS、JSON），让它们在 CommonJS（lib/）与 ES modules（es/）构建中保持原样可用。

在 VS Code 中调试 nwb 应用与测试

nwb 的调试方案依托 Chrome DevTools 协议：先在 VS Code 中安装Debugger for Chrome扩展，再向.vscode/launch.json添加如下配置：

{ "version": "0.2.0", "configurations": [ { "name": "Debug Dev Server", "request": "launch", "sourceMapPathOverrides": { "webpack:///src/*": "${webRoot}/*" }, "type": "chrome", "url": "http://localhost:3000", "webRoot": "${workspaceRoot}/src", }, { "name": "Debug Karma Tests", "request": "launch", "runtimeArgs": ["--headless"], "sourceMapPathOverrides": { "webpack:///src/*": "${workspaceRoot}/src/*", "webpack:///tests/*": "${workspaceRoot}/tests/*" }, "type": "chrome", "url": "http://localhost:9876/debug.html", } ] }

注意：上述配置假设你使用的是默认的主机与端口设置，并且请求的开发服务器端口当时可用。

两套配置的适用场景

• Debug Dev Server：面向开发服务器。先用npm start或nwb serve启动开发服务器，再在 VS Code 的 Debug 面板运行该配置（或按 F5），即可在 Chrome 中对运行中的应用打断点调试。nwb 开发服务器的默认端口为3000（DEFAULT_PORT = process.env.PORT || 3000，见 src/constants.js）；端口被占用时 nwb 会检测可用端口并交互式询问是否换端口运行（见 src/webpackServer.js），因此请以实际启动日志中的 URL 为准。sourceMapPathOverrides把 Webpack 生成的webpack:///src/*路径映射回磁盘上的src/目录，确保断点能命中源码行。
• Debug Karma Tests：面向测试。先用npm run test:watch或nwb test --server启动持续监听模式的测试服务器，再运行该配置调试测试用例。--headless运行时参数让 Chrome 以无头模式启动，sourceMapPathOverrides同时映射了src/与tests/两个目录。Karma 的调试入口页是http://localhost:9876/debug.html，这是 Karma 服务器提供给调试器的页面地址；nwb test的--server选项在 CLI 帮助中的说明为keep running tests on every change（见 src/cli.js），即文件变化时自动重跑测试，为调试会话持续提供新鲜上下文。

调试前的启动顺序

FAQ 明确建议的流程是：先启动被调试的一方，再在 VS Code 中启动调试配置。具体来说：

1. 调试开发服务器：npm start或nwb serve（确保http://localhost:3000可访问）；
2. 调试测试：npm run test:watch或nwb test --server（确保 Karma 服务器已就绪）；
3. 然后在 VS Code Debug 面板运行对应配置或按 F5。

小结：一份可复用的 FAQ 速查表

将上述问题归纳为一张速查表，方便日常查阅：

原 FAQ 还列出了“如何用 React Hot Loader 替代 React Transform”这一条目，但正文未展开。如果你在旧项目中遇到热更新相关需求，可结合 nwb 的devServer配置（如hot选项，默认true）与webpack.extra/webpack.config逃生舱机制（见 docs/Configuration.md）自行接入对应的热更新插件，并在改动前留意 nwb 当前版本内置的HotModuleReplacementPlugin行为（见 src/createWebpackConfig.js）。

以上解决方案均以当前仓库（nwb 源码与文档）为事实依据，配置片段可直接复制到你的nwb.config.js与.vscode/launch.json中使用。

• 开发工具
• 前端构建