Metalsmith 文件匹配指南：用 match() 按 Glob 模式精确筛选源文件-平芜编程栈

开发工具
CLI
前端

【免费下载链接】metalsmith

An extremely simple, pluggable static site generator for Node.js

项目地址：https://gitcode.com/gh_mirrors/me/metalsmith

导读

本文聚焦 Metalsmith（Node.js 极简可插拔静态站点生成器）中一个实用而关键的 API——match()文件匹配方法。它基于 glob 模式（micromatch 实现）对源目录中的文件路径进行筛选，是构建插件、实现静态文件跳过、增量更新等能力的公共基石。读完本文，你将掌握match()的完整参数语义、默认行为（如点文件处理）、与ignore()、statik()、watcher 的协作关系，并能结合仓库中的测试夹具与源码独立编写出可复用的匹配逻辑。

从测试夹具理解 match() 的"舞台"

match()的功能验证围绕仓库中的专用测试夹具展开：test/fixtures/match 目录下的src模拟了一个典型的混合内容源目录：

test/fixtures/match/src/ ├── .htaccess # 点文件（dotfile） ├── index.md # 带 frontmatter 的 Markdown 根文件 ├── nested/ │ └── index.md # 嵌套子目录中的 Markdown 文件 └── team.jpg # 二进制图片资源

其中 nested/index.md 全文仅一行nested body，无 frontmatter；而根目录 index.md 则带有date与title两个 frontmatter 字段。这个夹具刻意覆盖了：普通文件、点文件、嵌套路径、二进制资源四类典型对象，为下文每一项断言提供了确定的输入集合。

对应测试集中在 test/index.js 的describe('#match')块，共五条用例，逐一验证 glob 匹配、空输入容错、否定/OR 模式、点文件开关与 Windows 路径处理。

match() API 签名与三种调用形态

match()定义在 lib/index.js：

Metalsmith.prototype.match = function (patterns, input, options) { input = input || Object.keys(this._files) return match(input, patterns, options) }

它接收三个参数：

参数	类型	说明
`patterns`	`string \\| string[]`	一个或多个 glob 模式，必填
`input`	`string[]`（可选）	待匹配的字符串数组；缺省时使用当前已加载文件对象的键（即`Object.keys(this._files)`）
`options`	`object`（可选）	透传给 micromatch 的选项（`format`除外，见下文）

由此衍生出三种常见调用形态：

匹配当前已加载文件：在process()之后（文件已读入_files）直接调用m.match('**/*.md')，这是最常用的形态；
对任意字符串数组匹配：显式传入input，例如在 watcher 中对文件缓存键做匹配；
带选项匹配：传入{ dot: false }等 micromatch 选项，控制点文件参与与否。

深入源码：匹配到底发生在哪一层

Metalsmith.prototype.match只是薄薄一层包装，真正的匹配逻辑在 lib/helpers.js：

function match(input, patterns, options) { if (!(input && input.length)) return [] options = Object.assign({ dot: true }, options || {}, { // required to convert forward to backslashes on Windows and match the file keys properly format: normalize }) return micromatch(input, patterns, options).sort() }

可提炼四个关键实现事实：

空输入直接短路：input为空数组或空值时不抛错，直接返回[]——对应测试"should not error on falsy input"；
默认开启 dot 模式：Object.assign({ dot: true }, ...)使点文件（如.htaccess）默认参与匹配，除非调用方显式传{ dot: false }；
强制 format 为 path.normalize：这是跨平台正确性的关键——把 Windows 的反斜杠与 POSIX 的正斜杠统一归一化，保证 glob 模式与文件键能正确对位；且该参数被保留，调用方无法覆盖；
结果自动排序：返回前执行.sort()，保证匹配结果顺序确定、可断言。

match是helpers.js内部导出并被 lib/index.js 顶部解构引入的私有工具，不对外暴露，仅通过Metalsmith.prototype.match供外部使用。

典型匹配行为：从测试断言看语义

1. 基础 glob 匹配

const m = Metalsmith(fixture('match')) m.process(function (err) { const matches = m.match('**/*.md').join(',') // => index.md,nested/index.md })

**递归匹配任意层级，*.md匹配 Markdown 文件。注意返回的是相对源目录的路径字符串，嵌套文件保留其子目录前缀nested/index.md。

2. 否定模式（Negation）

const negationMatches = m.match('!index.md') // => ['.htaccess', 'nested/index.md', 'team.jpg']

以!开头的模式表示排除。上面的断言结果正好印证：排除根index.md后，夹具里剩余的三类文件全部命中——包括默认参与的点文件.htaccess。

3. 花括号 OR 模式

const orMatches = m.match('*.{jpg,md}') // => ['index.md', 'team.jpg']

{jpg,md}花括号扩展实现"多扩展名取其一"，且*不匹配斜杠，因此嵌套目录下的nested/index.md不会命中——这是 glob 语义中"单段通配"的典型体现。

4. 点文件开关

const matchesAll = m.match('**') // => ['.htaccess', 'index.md', 'nested/index.md', 'team.jpg'] const matchesNoDot = m.match('**', Object.keys(files), { dot: false }) // => ['index.md', 'nested/index.md', 'team.jpg']

默认dot: true时**命中全部四个对象；显式传{ dot: false }后.htaccess被排除。这解释了为什么仓库特意在夹具中放置.htaccess——它专门用于验证 dot 选项的默认值与覆盖能力。

5. Windows 路径不转换

最后一条用例通过一个插件把files中所有含/的键改写为\：

const matches = m.match('**/*.md') // => ['index.md', 'nested\\index.md']

断言确认match()不会把返回结果中的反斜杠转回正斜杠，保持输入原样，避免破坏插件已构建的 Windows 风格键名。

与 ignore() 的分工：过滤时机不同

ignore()（lib/index.js）作用于文件读取阶段：在read()递归遍历源目录时，把忽略规则交给 readdir 的 ignores 参数（字符串规则走 patternIgnores，函数规则走 fnIgnores），被忽略的文件根本不会被读入_files。

而match()作用于文件已加载之后，是对现存键集合的纯计算筛选，不改变_files本身。二者一前一后：ignore()决定"读什么进来"，match()决定"在已有集合里挑什么"。

实战：match() 的三处内部消费

match()的价值更多体现在它被高层功能调用：

1. 静态文件判定（statik）：在 lib/index.js 中，read()会把statik()声明的模式展开（目录模式追加/**，如['dir/subdir'] => ['dir/subdir', 'dir/subdir/**']），然后调用this.match(expandedPatterns, relpaths)判定哪些路径是静态资源。命中者被隔离到statik对象（只读属性、contents 为 Buffer），不进入插件处理流，最终在build()时被原样复制（lib/index.js）。对应测试见 test/index.js。

2. watcher 增量更新：文件监听器在目录被删除时，需要清理文件缓存中所有以该路径为前缀的条目，见 lib/watcher.js：

case 'unlinkDir': metalsmith.match(relPath, Object.keys(fileCache)).forEach((r) => delete fileCache[r]) break

这里把"目录路径"当作 glob 模式、把缓存键集合当作input，一条match()调用就完成了前缀式批量删除。

3. 插件开发：在.use(files => ...)插件中，files是{ '相对路径': File }的映射，配合m.match('**/*.md', Object.keys(files))可精确圈定要处理的文件子集，避免对每个键做手写正则。

小结与适用边界

match()的语义核心是 micromatch glob 匹配：支持**、!否定、{}扩展等语法，默认包含点文件，返回排序后的相对路径数组，跨平台由内部normalize保证；
三个参数中只有patterns必填，input缺省即当前文件键，options可覆盖 dot 等行为但format被锁定；
实践要点：空输入返回空数组（可安全短路）；不要在read()之前调用（此时_files为空）；需要排除文件优先考虑ignore()，需要筛选已加载文件优先考虑match()；
需要深入了解时，可继续研读 lib/helpers.js 的实现、lib/index.js 的 API 文档，以及 test/index.js 的完整用例集。