@kinngyo/weapack

基于 Vinyl Stream 的小程序组件构建工具。它负责加载配置、调度多条构建管道、处理 watch 重建，并通过插件扩展文件转换能力。

安装

npm install -D @kinngyo/weapack

要求 Node.js >=20.19.0。

快速开始

在项目根目录创建 weapack.config.ts：

import { defineConfig } from '@kinngyo/weapack'

export default defineConfig({
    input: 'src/**/*',
    base: 'src',
    outDir: 'dist',
})

启动监听构建：

npx weapack watch

执行一次构建：

npx weapack build

watch 是默认命令，也可以直接执行：

npx weapack

CLI

weapack
weapack watch
weapack build

| 选项 | 说明 | 默认行为 | | --- | --- | --- | | -m, --mode <mode> | 覆盖运行模式 | build 为 production，watch 为 development | | -o, --out-dir <outDir> | 覆盖输出目录 | 使用配置文件的 outDir，否则为 dist | | -c, --config <config> | 指定配置文件路径或查找前缀 | 查找 weapack.config | | -l, --log-level <level> | 设置日志级别，支持 silent、normal、verbose | normal | | --cwd <cwd> | 指定工作目录 | 当前命令执行目录 |

配置文件

默认查找 weapack.config.{ts,mts,cts,js,mjs,cjs}。也可以通过 CLI 的 --config 或 API 的 config 参数指定配置文件。

import { defineConfig } from '@kinngyo/weapack'

export default defineConfig({
    name: 'weapp',
    input: 'src/**/*',
    outDir: 'dist',
    base: 'src',
    outExtension: {
        '.css': '.wxss',
    },
    define: {
        __DEV__: process.env.NODE_ENV !== 'production',
    },
})

函数式配置会收到当前命令和模式：

import { defineConfig } from '@kinngyo/weapack'

export default defineConfig(env => ({
    input: 'src/**/*',
    define: {
        __COMMAND__: env.command,
        __DEV__: env.mode === 'development',
    },
}))

配置数组会独立生成多条构建管道：

import { defineConfig } from '@kinngyo/weapack'

export default defineConfig([
    {
        name: 'static',
        input: 'src/**/*.{json,wxml,wxs}',
        base: 'src',
    },
    {
        name: 'style',
        input: 'src/**/*.css',
        base: 'src',
        outExtension: { '.css': '.wxss' },
    },
])

配置字段

| 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | name | string | 否 | pipeline 名称，用于日志、错误提示和 manifest 记录 | | root | string | 否 | 项目根目录，默认使用命令执行目录 | | input | string \| string[] | 是 | 传给 vinyl-fs.src 的匹配规则，支持 ! 排除模式 | | outDir | string | 否 | 输出目录，支持相对路径或绝对路径，默认 dist | | base | string | 否 | 计算输出相对路径的基础目录，默认从 input 推导 | | plugins | WeapackPluginInput[] | 否 | 转换插件列表 | | outExtension | Record<string, string> | 否 | 输出扩展名映射，例如 { '.css': '.wxss' } | | define | Record<string, unknown> | 否 | 产物文本替换映射，非字符串值会自动 JSON.stringify | | watch | WeapackWatchConfig | 否 | watch 行为配置 |

input 会以 root 为 cwd 读取文件，base 会作为 Vinyl 文件的基础目录。未显式设置 base 时，weapack 会从第一条非排除 input 中推导基础目录。

define

define 是写入产物前执行的纯文本替换：

export default defineConfig({
    input: 'src/**/*',
    define: {
        __APP_NAME__: 'demo',
        __DEV__: true,
    },
})

上面的配置会把文本产物中的 __APP_NAME__ 替换为 demo，把 __DEV__ 替换为 true。二进制内容会跳过替换。

这不是 AST 级常量折叠，也不会只处理 JS/TS 标识符边界。如果需要更精确的 JavaScript/TypeScript 常量替换，建议放在对应语言插件中处理。

watch 配置

export default defineConfig({
    input: 'src/**/*',
    watch: {
        rebuildOnUnlink: true,
        debounceMs: 100,
        incremental: 'file',
    },
})

| 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | debounceMs | number | 100 | 文件变化触发重建前的防抖时间，单位毫秒 | | rebuildOnUnlink | boolean | true | 删除源文件并清理旧产物后，是否再触发一次重建 | | incremental | false \| 'file' \| 'dependency' | false | watch 增量策略 | | resolveAffectedFiles | WeapackResolveAffectedFilesHook | 返回空数组 | 依赖感知增量时用于计算受影响的输入文件 |

增量策略：

| 值 | 行为 | | --- | --- | | false | 文件变化后执行全量 pipeline | | 'file' | 仅对 add/change 的文件执行文件级 pipeline；unlink 只清理旧产物，是否继续重建由 rebuildOnUnlink 控制 | | 'dependency' | 通过 resolveAffectedFiles 计算受影响文件；change/add 返回空数组时回退全量重建 |

resolveAffectedFiles 返回的路径会基于 root 解析：

export default defineConfig({
    input: 'src/**/*',
    watch: {
        incremental: 'dependency',
        resolveAffectedFiles(changedFile) {
            if (changedFile.path.endsWith('.scss')) {
                return ['src/pages/home/index.scss']
            }

            return [changedFile.path]
        },
    },
})

API

import { Weapack } from '@kinngyo/weapack'

const weapack = new Weapack()

await weapack.build()
const watcher = await weapack.watch()
await watcher.close()

build 未预设 NODE_ENV 时会设置为 production，默认 mode 为 production。watch 未预设 NODE_ENV 时会设置为 development，默认 mode 为 development。

await weapack.build({ mode: 'development' })
await weapack.build({ outDir: 'release' })
await weapack.build({ cwd: 'examples/weapp', config: './custom.config.ts' })
await weapack.watch({ logLevel: 'verbose' })

也可以直接使用函数式 API：

import { build, watch } from '@kinngyo/weapack'

await build({ outDir: 'dist' })
const watcher = await watch()
await watcher.close()

插件

插件通过 definePlugin 创建，transform 需要使用内置 adapter：textTransform、fileTransform 或 streamTransform。

文本转换

import { definePlugin, textTransform } from '@kinngyo/weapack'

export const replacePlugin = definePlugin({
    name: 'replace',
    transform: textTransform(content => content.replaceAll('__APP_NAME__', 'demo')),
})

文件转换

import { definePlugin, fileTransform } from '@kinngyo/weapack'

export const bannerPlugin = definePlugin({
    name: 'banner',
    transform: fileTransform(file => ({
        relativePath: file.relativePath,
        contents: `/* ${file.relativePath} */\n${file.text ?? ''}`,
    })),
})

文件转换函数可返回 string、Buffer、WeapackFile、WeapackFileResult、数组、null 或 undefined。返回 null 表示丢弃当前文件；返回 undefined 表示沿用当前文件内容。

Stream 转换

import { Transform } from 'node:stream'
import { definePlugin, streamTransform } from '@kinngyo/weapack'

export const streamPlugin = definePlugin({
    name: 'stream',
    transform: streamTransform(
        () =>
            new Transform({
                objectMode: true,
                transform(file, _encoding, callback) {
                    callback(null, file)
                },
            }),
    ),
})

插件工厂

插件工厂会收到当前命令、模式、工作目录和项目根目录：

import { definePlugin, textTransform } from '@kinngyo/weapack'

export const modePlugin = definePlugin(context =>
    definePlugin({
        name: 'mode',
        transform: textTransform(content => content.replaceAll('__MODE__', context.mode)),
    }),
)

插件执行顺序

插件可通过 enforce 控制顺序：

| 值 | 执行时机 | | --- | --- | | 'pre' | 普通插件前 | | undefined | 默认顺序 | | 'post' | 普通插件后 |

插件全部执行完成后，weapack 会依次执行 define 文本替换、outExtension 输出扩展名映射、写入日志和文件输出。

公开导出

入口当前导出 config、constants、helper、logger、main、manifest、pipeline、transform、types、utils、watcher 中的成员，并额外导出 version。

常用导出：

| 导出 | 说明 | | --- | --- | | Weapack | 构建工具入口类 | | build | 执行一次构建 | | watch | 启动监听构建 | | defineConfig | 配置类型辅助函数 | | definePlugin | 插件类型辅助函数 | | textTransform | 文本转换 adapter | | fileTransform | 文件转换 adapter | | streamTransform | Stream 转换 adapter | | logger | 日志工具 | | version | 当前包版本 | | 类型定义 | WeapackUserConfig、WeapackPlugin、WeapackPluginInput、WeapackFile 等公开类型 |