Google Wireit 项目配置参考指南

Google Wireit 项目配置参考指南

wireit Wireit upgrades your npm/pnpm/yarn scripts to make them smarter and more efficient. 项目地址: https://gitcode.com/gh_mirrors/wi/wireit

前言

Google Wireit 是一个强大的 JavaScript 任务运行器，它通过扩展 package.json 文件中的脚本定义，为开发者提供了更精细的任务控制能力。本文将全面解析 Wireit 的配置选项、依赖语法和环境变量设置，帮助开发者充分利用这一工具提升构建效率。

核心配置属性

在 package.json 文件的 wireit.<script> 对象中，可以配置以下关键属性：

基础配置

1. command (字符串)

   • 定义要执行的 shell 命令
   • 这是 Wireit 执行的核心指令

2. dependencies (字符串数组)

   • 指定当前脚本运行前必须完成的其他脚本
   • 支持跨包依赖引用

文件管理

3. files (字符串数组)

   • 定义输入文件的 glob 模式
   • 用于计算脚本的指纹(fingerprint)
   • 可以引用父目录中的文件(使用 ../ 语法)

4. output (字符串数组)

   • 定义输出文件的 glob 模式
   • 用于缓存和清理操作
   • 只能引用当前包内的文件

高级控制

5. clean (布尔值或字符串)

   • 控制是否在执行前清理输出文件
   • 可选值：
     • true: 总是清理
     • false: 从不清理
     • "if-file-deleted": 仅当文件被删除时清理

6. packageLocks (字符串数组)

   • 指定要考虑的包锁文件
   • 默认包含 package-lock.json
   • 这些文件会影响脚本的指纹计算

依赖关系语法详解

Wireit 提供了灵活的依赖声明方式：

同包依赖

"dependencies": ["build"]

表示依赖当前包中的 build 脚本

跨包依赖

"dependencies": ["../shared:compile"]

表示依赖位于 ../shared 目录下包中的 compile 脚本

环境变量配置

Wireit 提供了多个环境变量来控制其行为：

并行控制

1. WIREIT_PARALLEL
   • 控制同时运行的最大脚本数量
   • 默认值为逻辑 CPU 核心数的 2 倍
   • 可设置为正整数或 infinity

缓存策略

2. WIREIT_CACHE

   • 控制缓存行为模式
   • 可选值：
     • local: 使用本地磁盘缓存
     • github: 使用 GitHub Actions 缓存
     • none: 禁用缓存
   • 默认值取决于 CI 环境

3. CI

   • 影响 WIREIT_CACHE 的默认值
   • 在 CI 环境中通常自动设置为 true
   • 必须精确设置为 true 才有效

文件匹配模式

Wireit 支持丰富的 glob 模式语法：

基本模式

• src/*.js - 匹配 src 目录下所有 JS 文件
• assets/**/* - 递归匹配 assets 目录下所有文件
• config.{json,yaml} - 匹配 config.json 或 config.yaml

排除模式

• !temp/* - 排除 temp 目录下所有文件

注意事项

1. 始终使用 / 作为路径分隔符
2. 路径相对于当前包解析
3. 目录匹配会自动包含其所有子内容
4. 排除模式的顺序很重要
5. 模式区分大小写

指纹计算机制

Wireit 使用指纹(fingerprint)来优化构建过程，其计算考虑以下因素：

1. 配置相关

   • 命令字符串
   • 清理设置
   • 输出模式

2. 文件内容

   • 所有匹配 files 模式的文件内容哈希
   • 所有匹配 packageLocks 的锁文件内容哈希

3. 系统环境

   • 操作系统平台
   • CPU 架构
   • Node.js 版本

4. 依赖关系

   • 所有传递性依赖的指纹

在 GitHub Actions 环境下，还会考虑：

• 系统镜像版本(通过 ImageOS 环境变量)

最佳实践建议

1. 合理设置依赖：明确脚本间的依赖关系，确保执行顺序正确

2. 精细控制文件匹配：

   • 为 files 指定精确的输入文件
   • 为 output 明确定义所有输出位置

3. 利用缓存机制：

   • 本地开发使用 local 缓存
   • CI 环境考虑使用 github 缓存

4. 并行优化：

   • 根据机器性能调整 WIREIT_PARALLEL
   • 对于 I/O 密集型任务可适当增加并行度

5. 清理策略：

   • 对于确定性强的任务使用 clean: true
   • 对于可能增量生成的文件考虑 if-file-deleted

通过合理配置这些选项，开发者可以充分利用 Wireit 的强大功能，实现高效、可靠的自动化构建流程。

wireit Wireit upgrades your npm/pnpm/yarn scripts to make them smarter and more efficient. 项目地址: https://gitcode.com/gh_mirrors/wi/wireit