ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

在 Brunch 中接入 TypeScript:typescript-brunch 插件安装、配置与错误处理实战指南

在 Brunch 中接入 TypeScript:typescript-brunch 插件安装、配置与错误处理实战指南 构建工具前端【免费下载链接】brunch Web applications made easy. Since 2011.项目地址https://gitcode.com/gh_mirrors/br/brunch点击查看免费下载本篇指南围绕 Brunch 官方生态中的 typescript-brunch 插件展开说明如何为 Brunch 项目添加 TypeScript 编译能力、如何通过brunch-config与tsconfig.json定制编译选项以及如何应对插件逐文件隔离编译带来的误报错误。读完本文你将掌握从安装、配置到调试的一整套 TypeScript Brunch 实战方案。一、typescript-brunch 是什么typescript-brunch 是 Brunch 的一个编译类插件其唯一职责是Adds TypeScript support to Brunch——即让 Brunch 能识别并编译.ts/.tsx源文件将其产出为 JavaScript 后进入 Brunch 的打包流程。它位于本仓库的 packages/addons/typescript-brunch/ 目录属于 Brunch 官方维护的 addon 插件集。从 package.json 可以确认它的关键元信息项目值说明当前版本3.0.0-pre预发布版本对应 Brunch 3.x 主线入口文件./index.jsmain字段指向的插件主文件发布文件index.js、transpile.jsfiles字段声明运行时依赖anymatch^3.1用于路径匹配决定哪些文件被忽略对等依赖typescript^3.0.0需要项目自行安装 TypeScript 编译器Node 要求node 10.16engines字段约束测试脚本eslint .仓库中以 ESLint 校验代码风格在 index.js 末尾插件以三个原型属性声明自己的 Brunch 插件身份TypeScriptCompiler.prototype.brunchPlugin true; TypeScriptCompiler.prototype.type javascript; TypeScriptCompiler.prototype.pattern /\.tsx?$/;brunchPlugin trueBrunch 在加载依赖时会识别这一标记把该模块实例化为编译插件参见 Brunch 插件加载逻辑type javascript产出物属于 JavaScript 管道可被后续的 JS 优化器如 minify、terser-brunch继续处理pattern /\.tsx?$/默认匹配.ts与.tsx文件。二、安装两条接入路径2.1 推荐方式一条命令安装插件与编译器npm install --save-dev typescript-brunch typescript注意这里需要同时安装两个包typescript-brunch是 Brunch 侧的插件壳真正的编译能力来自 TypeScript 编译器本身typescript被声明为 peerDependencies。只装插件而不装typescript编译时require(typescript)将无法解析。2.2 手动方式精确控制版本如果你更习惯手写package.json可以按如下方式操作在package.json中添加依赖typescript-brunch: x.y。文档明确建议选取一个与你所用 Brunch 的 major.minorx.y版本对应的插件版本避免插件 API 与 Brunch 核心不匹配TypeScript 编译器仍需手动安装npm install --save-dev typescript若希望使用插件的 git 开发版可声明为typescript-brunch: github:brunch/typescript-brunch。安装完成后Brunch 会自动发现该插件。以 lib/utils/plugins.js 的实现来看Brunch 会从项目的dependencies/devDependencies中筛选名称包含brunch的包实例化具备brunchPlugin标记的模块并注入当前配置。随后 plugin-adapter 会把插件的compile等方法统一包装为 Promise 形式因此该插件返回 Promise 的compile实现可直接被 Brunch 管道消费。三、编译配置tsconfig.json 与 brunch-config 的优先级3.1 优先级规则插件在构造时按以下顺序组装编译选项对应 index.js若项目根目录存在tsconfig.json其compilerOptions会被读取并作为默认值读取逻辑见getTsconfig路径为config.paths.root下的tsconfig.jsonbrunch-config.js/brunch-config.coffee中plugins.brunchTypescript下的选项会覆盖上述默认值仍有部分选项由插件内部强制决定见下文核心实现一节。3.2 brunch-config 配置示例module.exports { // ... plugins: { brunchTypescript: { removeComments: true } } };从源码看该插件会遍历plugins.brunchTypescript对象中的所有键除sourceMap、ignore两个特殊键外逐项覆盖到最终编译选项上const options config.plugins config.plugins.brunchTypescript || {}; this.options getTsconfig(config.paths config.paths.root); Object.keys(options).forEach(key { if (key sourceMap || key ignore) return; this.options[key] options[key]; });这意味着你可以在brunch-config中直接写 TypeScript 编译器选项例如target、module、jsx、removeComments等它们会合并并覆盖tsconfig.json中的同名项。3.3 未提供任何选项时的默认值若既不提供tsconfig.json也不配置plugins.brunchTypescript插件默认使用{ target: es5, module: commonjs, emitDecoratorMetadata: true, experimentalDecorators: true }即默认编译目标为 ES5、模块格式为 CommonJS并默认开启装饰器元数据发射与实验性装饰器语法支持适合 Angular 等依赖装饰器的技术栈。源码中这两项是通过非false即开启的方式实现的this.options.emitDecoratorMetadata this.options.emitDecoratorMetadata ! false; this.options.experimentalDecorators this.options.experimentalDecorators ! false;因此只要没有显式设为false它们就保持开启——这正好与文档默认值一致。3.4 枚举型选项的容错解析target、module、jsx这类选项既可以是枚举数字TypeScript 内部数值也可以是字符串名。插件通过resolveEnumindex.js做容错归一未提供时返回默认值1对应 CommonJS / ES5 / Preserve JSX是数字时原样保留是字符串时与ts.ModuleKind/ts.ScriptTarget/ts.JsxEmit的键名做大小写不敏感匹配找不到则回落默认值。this.options.module resolveEnum(this.options.module, ts.ModuleKind); this.options.target resolveEnum(this.options.target, ts.ScriptTarget); this.options.jsx resolveEnum(this.options.jsx, ts.JsxEmit);3.5 与 Brunch 全局配置的联动还有几个选项不受brunchTypescript直接控制而是联动 Brunch 全局配置行为实现位置说明生成 source mapthis.options.sourceMap !!config.sourceMaps;跟随 Brunch 的sourceMaps全局开关忽略 vendor 目录anymatch(options.ignore \|\| config.conventions.vendor)可传自定义ignore数组否则遵循 Brunch 默认的 vendor 约定自定义匹配模式this.options.pattern在插件配置中写pattern可覆盖默认的/\.tsx?$/noEmitOnError强制为falsethis.options.noEmitOnError false;逐文件隔离编译模式下必须允许发射输出moduleResolution被删除delete this.options.moduleResolution;避免在隔离编译下触发模块解析相关误报四、核心实现逐文件隔离编译与产出物处理4.1 为什么每个文件单独编译该插件在compile(params)阶段index.js对每个匹配的文件单独调用transpileModule并传入reportDiagnostics: true以收集诊断信息。而 transpile.js 是真正的转译核心它在调用 TypeScript 编译器时强制设置了一系列选项options.isolatedModules true; // 以隔离模块模式编译单文件 options.suppressOutputPathCheck true; // 不检查输入输出路径冲突 options.allowNonTsExtensions true; // 允许非 .ts 扩展名文件 options.noLib true; // 不加载 lib 声明文件避免找不到 lib 报错 options.lib undefined; // 与 noLib 配套 options.noResolve true; // 不做整体上下文解析避免缺失文件报错 options.noEmit false; // 明确要求发射输出从代码注释可以清晰看出设计意图transpileModule不写磁盘、不参与整个 TypeScript 项目的类型检查只做单文件语法转译因此noLib、noResolve等开关都是为了把上下文问题排除在报错之外。4.2 诊断收集与内置过滤当reportDiagnostics为真时会依次收集语法诊断、语义诊断与选项诊断。其中语义诊断会经过一层内置过滤器忽略以下五个高频误报错误码定义在 transpile.js错误码含义1208在--isolatedModules下无法编译命名空间2307找不到模块2304找不到名称2322类型不可赋值2339属性在类型上不存在4.3 产出物与 source map 修正编译成功后插件返回{data, map}输出文本会统一追加换行符result {data:${compiled.outputText || compiled}\n}若 TypeScript 发射了 source map插件会解析并修正sources[0]为原始文件路径让 Brunch 能把映射合并到最终 bundle 上对应代码注释Fix the sources path so Brunch can merge them。五、错误报告机制与 ignoreErrors 配置5.1 误报的来源插件 README 明确说明从版本 1.8.2 起插件可能报告一些意料之外的 TypeScript 错误。原因是该插件对每个文件单独、隔离地编译不利用完整的 TypeScript 项目上下文——跨文件类型推断、依赖解析在单文件视角下天然不完整因此会出现假阳性错误。5.2 ignoreErrors 的演进与用法针对这一问题插件提供了ignoreErrors配置其能力随版本演进1.8.3 起可在brunch-config的插件配置对象中加入ignoreErrors值为错误码数组用于屏蔽指定错误2.0.0尝试支持ignoreErrors: true忽略全部错误但该版本实现有缺陷2.0.1 起ignoreErrors: true恢复正常可一键忽略所有 TypeScript 错误数组用法依旧有效。对应的源码实现位于 index.js 与编译阶段的过滤逻辑if (this.options.ignoreErrors) { if (this.options.ignoreErrors true) { this.ignoreAllErrors true; } else { this.ignoreErrors new Set(this.options.ignoreErrors); } delete this.options.ignoreErrors; } // ... if (this.ignoreAllErrors true) { reportable []; } else if (this.ignoreErrors) { reportable reportable.filter(err !this.ignoreErrors.has(err.code)); }即ignoreErrors: true直接把可报告的诊断清空数组则按错误码过滤。未被过滤的错误会拼成可读信息并 reject形如Error 2322: Type x is not assignable... (Line: N, Col: M)行列号通过err.file.lineMap换算见errPos辅助函数。5.3 推荐实践用 tsc 做真正的类型检查README 指出插件作者希望在brunch build中支持完整的语言服务language service但在此之前建议把tsc --noEmit加入你的测试脚本或构建脚本用完整的 TypeScript 项目级检查来捕获真正的错误tsc --noEmit同时强调插件的误报不会影响编辑器 / IDE 的 TypeScript 支持你仍然可以依赖编辑器获得准确的类型诊断。六、使用注意事项与适用前提版本对应为package.json手动添加插件时应选择与你 Brunch 主版本major.minor匹配的typescript-brunch版本本仓库当前版本为3.0.0-pre面向 Brunch 3.x。TypeScript 必须自装插件不内置编译器typescript^3.0.0是 peerDependency。Node 版本插件要求 Node 10.16使用更旧运行时需自行评估。误报预期跨文件类型信息、模块解析类错误可能以误报形式出现优先用ignoreErrors数组精确屏蔽已知噪声如 2304/2307/2322/2339或整体开启ignoreErrors: true并配合tsc --noEmit做权威校验。vendor 与 ignore默认遵循 Brunch 的conventions.vendor忽略约定如需自定义排除规则可在plugins.brunchTypescript.ignore中提供 anymatch 兼容的匹配模式。七、许可与贡献者该插件以 MIT 协议开源许可证全文见 LICENSE。README 中列出的主要贡献者包括 Baptiste Donaux作者、Colin Bate、Kristóf Poduszló、Joshua Poehls、xtity 等。其完整文档含本节所述全部用法可在 packages/addons/typescript-brunch/README.md 中查阅插件行为细节可深入 index.js 与 transpile.js 两处源码或参考 Brunch 核心的插件加载机制 lib/utils/plugins.js 与 lib/utils/plugin-adapter.js 进一步理解插件如何被实例化与调用。赞分享构建工具前端【免费下载链接】brunch Web applications made easy. Since 2011.项目地址https://gitcode.com/gh_mirrors/br/brunch点击查看免费下载相关推荐Jeepay 聚合支付系统如何部署从 0 到跑通微信支付宝云闪付的完整指南Jeepay 聚合支付系统如何部署从 0 到跑通微信支付宝云闪付的完整指南 如果你要同时接入微信支付、支付宝和云闪付光签名规则、回调格式、订单查询接口就不止构建工具前端postcss-brunch 集成指南在 Brunch 中使用 PostCSS 处理与 CSS Modulespostcss brunch 集成指南在 Brunch 中使用 PostCSS 处理与 CSS Modules 导读 本文聚焦 brunch 仓库中的 pos构建工具前端less-brunch 插件全指南在 Brunch 中编译 LESS、配置编译器选项与启用 CSS Modulesless brunch 插件全指南在 Brunch 中编译 LESS、配置编译器选项与启用 CSS Modules 导读 本文以 less brunch ht构建工具前端上一篇BlockNote 完全移除 UI 元素打造纯净的无工具栏编辑器源码级解析下一篇globe夜间模式探索如何用ASCII字符模拟地球昼夜交替创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表