endef

endef 是一个纯 Node.js 的文件旁路转换工具。

它适合这样的场景：某些常见源码或文本后缀的文件在系统读取、复制、粘贴、编辑器打开时出现乱码或异常，但通过 Node.js 脚本读取仍然正常。endef 会先把目标文件内容写到同目录的 .endef 副本里，再用脚本批量删除原文件并把 .endef 改回原文件名。

示例：

src/App.vue -> src/App.vue.endef -> src/App.vue
src/main.ts -> src/main.ts.endef -> src/main.ts
README.md -> README.md.endef -> README.md

endef 不是杀毒工具，也不能保证绕过所有拦截方式。建议在干净系统、离线磁盘、PE 或 Linux Live 环境里使用，恢复后仍然需要做安全扫描和人工抽查。

特性

• Node.js CLI，恢复阶段可自动调用 Bash 或 PowerShell 脚本
• 默认旁路后缀为 .endef
• en 默认转换所有匹配后缀的文件
• de 会用脚本批量删除原文件，并把 .endef 临时副本改回原文件名
• pack 会把恢复后的目录打包成 .tar.gz
• 不引入生产依赖

环境要求

推荐 Node.js 22 或更高版本。

安装

npm install -g endef

快速开始

生成 .endef 副本：

endef en /path/to/project

用脚本批量删除原文件，并把 .endef 改回原文件名：

endef de /path/to/project

打包当前目录：

endef pack

默认会使用当前目录名生成压缩包。例如当前目录是 foo，会生成：

foo.tar.gz

指定输出文件名：

endef pack recovered

会生成：

recovered.tar.gz

命令

endef en [directory] [options]
endef de [directory] [options]
endef pack [name] [options]
endef all [directory] [options]

en 会扫描目标目录，把匹配后缀的文件读取出来，并写成同目录的 .endef 副本。

de 会扫描目标目录中的 .endef 文件，并用外部脚本批量删除原文件、把 .endef 改回原文件名。默认模式是 auto：优先使用 Bash 的 find + xargs -P，没有 Bash 时在 Windows 上使用 PowerShell。这个命令会直接修改文件，请在执行前确认目录和备份策略。

pack 会按当前配置扫描当前目录，把没有被 excludeDirs 排除的文件打包成 .tar.gz。如果输出文件已存在，会直接覆盖。

all 会按顺序执行 en、de、pack，适合确认配置后一次性完成旁路转换、脚本恢复和打包。

参数

--config <file>       使用指定配置文件
--suffix <suffix>     旁路文件后缀，默认：.endef
--ext <list>          目标文件后缀，多个值用英文逗号分隔
--exclude <list>      排除目录名，多个值用英文逗号分隔
--concurrency <n>     并发文件操作数量
--out <file>          压缩包输出名称
--mode <mode>         de/all 恢复模式：auto、bash、powershell、node
--verbose             输出处理明细

示例：

endef en . --ext .js,.ts,.vue,.md --exclude node_modules,.git,dist
endef de .
endef pack recovered
endef all . --out recovered

配置文件

endef 会按下面的顺序读取配置，后面的配置覆盖前面的配置：

用户目录：~/.endef/config.json
当前目录：.endef.json
命令参数：优先级最高

配置示例：

{
  "suffix": ".endef",
  "extensions": [
    ".js",
    ".jsx",
    ".cjs",
    ".mjs",
    ".mts",
    ".ts",
    ".tsx",
    ".vue",
    ".md",
    ".yaml",
    ".yml",
    ".json",
    ".type.ts",
    ".scss",
    ".css",
    ".html",
    ".txt",
    ".env",
    ".c",
    ".h",
    ".hpp",
    ".java",
    ".svn-base",
    ".lock",
    ".git",
    ".gitconfig",
    ".less"
  ],
  "excludeDirs": ["node_modules", ".git", "dist", ".next", ".nuxt", ".cache"],
  "excludeFiles": [".endef.json"],
  "concurrency": 32
}

恢复策略

恢复时，endef 会把：

file.ext.endef

恢复为：

file.ext

de 默认使用脚本恢复。auto 模式会优先尝试 Bash，因为 find + xargs -P 可以并行处理大量文件；如果没有 Bash，则在 Windows 上使用单个 PowerShell 进程批量处理。恢复时会把：

file.ext.endef

改回：

file.ext

如果 file.ext 已经存在，会先被删除。这个行为符合工具的核心假设：原文件可能已经被异常内容污染，而 .endef 是通过旁路读取保存出来的可恢复内容。

打包策略

打包命令：

endef pack

默认输出会使用当前目录名。例如当前目录是 foo，默认输出：

foo.tar.gz

如果指定：

endef pack baz

则输出：

baz.tar.gz

pack 会沿用配置里的 excludeDirs，也支持命令行临时指定：

endef pack --exclude node_modules,.git,dist

打包时会自动跳过：

• 被 excludeDirs 排除的目录
• 输出压缩包自身
• 残留的 .endef 临时副本

压缩包格式是 .tar.gz，不需要额外生产依赖。

一步执行

如果已经确认配置，可以使用：

endef all .

它等价于依次执行：

endef en .
endef de .
endef pack

同样支持排除目录和输出名称：

endef all . --exclude node_modules,.git,dist --out recovered

安全建议

• 操作前尽量手动备份目录或磁盘
• 优先在干净系统、离线环境或挂载出来的磁盘上运行
• 先在小目录中测试 endef en 和 endef de
• 不要直接运行恢复出来的未知脚本或可执行文件
• 恢复后建议做杀毒、哈希校验和人工抽查

License

MIT