一个项目有三份配置:基础配置、本地覆盖、生产覆盖。基础配置里写数据库端口 5432,本地覆盖改成 15432,生产又写一遍 5432。某次基础配置改了端口,另外两份没跟着改,本地能跑,生产连接失败。你想把公共部分抽出来只写一次,用 JSON 又没有引用语法,用 JS 拼对象又变成一堆 Object.assign,谁覆盖谁全靠阅读顺序。
VarJson 是给这种「配置由多个文件和多个作用域拼起来」的场景写的。它用一个叫 .vjson 的文本格式,把配置拆成若干「零件」,再通过入口文件的 var 汇总成一份普通 JS 对象。这一篇会把它能做的事、完整 API、容易踩的坑,以及它和同类方案(JSON、JS 模块、YAML)的边界讲清楚。
事故现场:同一份配置写三遍
先把要解决的问题拆开。配置其实有两类信息:一类是「事实」,比如服务地址、端口、密钥;另一类是「组装规则」,比如开发环境用本地地址、生产环境用网关地址、某些字段从公共配置继承。JSON 只能表达事实,不能表达「这个字段来自另一个文件」;JS 对象能表达引用,但引用关系散落在代码里,改配置的人不一定会读代码。
VarJson 的做法是把这两类信息都放进配置文本:事实写在不同的作用域里,组装规则用 & 引用表达。最终交给程序的仍然是一个普通对象,不需要运行时再解释什么格式。
它到底是什么:零件与唯一出口
仓库 README 的第一句话是「把分散的配置片段组装成一份可在程序里直接使用的 JS 对象」。这句话里最关键的是「出口」:一个 .vjson 文件里可以有多个顶层作用域,比如 tops、var,也可以有自定义作用域,但 parse 只返回入口文件的 var。其他作用域都是零件,不会直接出现在结果里。
var,最终返回的就是它tops,通常放基础事实,跨文件引用时省略别名直接访问&!名字 从别的文件访问import 进来的其他 .vjson 文件,按别名寻址它明确不是 DSL:没有函数、运算、分支、循环。你在里面写不了 port + 1,也写不了「如果环境是生产就用这个」。需要这些逻辑,应该在生成配置之前用代码算好,再把结果写进文本。这个限制听起来笨,但它换来的是可静态读取、可序列化、可被编辑器插件处理的配置结构。
文本格式本身比 JSON 宽松一些:支持 // 行注释和 /* */ 块注释;数字支持十六进制 0x、八进制 0o、二进制 0b、科学计数法,以及下划线和逗号分隔。实测同一段配置里的 0x1f、0o17、0b1010、1_000、1,000、1.5e-3 分别解析成 31、15、10、1000、1000、0.0015。字符串支持单双引号,也处理常见转义。但别因此把它当通用格式:它仍然只是 VarJson 自己的方言,标准 JSON 解析器读不了注释、引用和这些数字写法。
安装与跑通:它没有发布到 npm
先说不顺利的部分,免得你照着 README 卡住。这个包没有发布到 npm,npm install varjson 会得到 404:
npm error code E404
npm error 404 Not Found - GET https://registry.npmjs.org/varjson - Not found
仓库的 package.json 也不像一个可发布包:version 是 1.0.0,main 指向不存在的 index.js,test 脚本还是 npm init 默认的报错脚本,TypeScript 和 Vitest 被放在 dependencies 而不是开发依赖里。仓库最新提交的说明是 v1.1.3,和 package.json 的 1.0.0 对不上,标为待确认。结论是:把它当源码用,不要当 npm 包用。
正确路径是 clone 仓库,直接跑它自带的测试。README 写的命令是:
node --experimental-strip-types test/test.ts
实际会失败,因为测试文件在 src/test/test.ts,根目录没有 test 目录:
Error: Cannot find module '.../VarJson/test/test.ts'
改成实际路径就能跑:
git clone https://github.com/Deepl-ysp/VarJson.git
cd VarJson
node --experimental-strip-types src/test/test.ts
本机 Node 24.21.0 下,输出结尾是:
Results: 48 passed, 0 failed
本文所有示例都在这个版本上跑过。Node 22.6 及以上可以用 --experimental-strip-types 直接跑 .ts;更老的 Node 需要 tsx 或先编译,这一条未在本机实测。README 里 import { parse } from "./index.ts" 也和实际结构不符:根目录没有 index.ts,真实的入口是 src/index.ts。把 src 整个拷进项目后,按 ./varjson/index.ts 引入即可,这个文件路径问题标为待确认。
最小示例:两个文件,一个出口
建两个文件。第一个放公共事实,第二个是入口,只负责挑字段:
// base.vjson
tops = {
host = "localhost",
port = 8080,
secrets = { token = "s3cr3t" }
};
var = {
neverSeen = "dependency-var"
};
// app.vjson
import "./base.vjson" as base;
var = {
host = &base.host,
port = &base.port,
token = &base.secrets.token,
endpoint = "http://localhost:8080"
};
入口脚本:
import { fileURLToPath } from "node:url";
import { parse, stringify } from "./VarJson/src/index.ts";
const entry = fileURLToPath(new URL("./app.vjson", import.meta.url));
const cfg = await parse(entry);
console.log(JSON.stringify(cfg));
实际输出:
{"host":"localhost","port":8080,"token":"s3cr3t","endpoint":"http://localhost:8080"}
三个点值得注意。第一,base.vjson 里的 var.neverSeen 没有出现在结果里,因为入口是 app.vjson,只取它的 var。第二,&base.host 直接拿到了 base 的 tops.host,写法上省略了 tops。第三,endpoint 不能写成 "http://" + &base.host,因为语言里没有运算符,只能写完整字面量,或者用两个字段分别表达。
API 全覆盖:parse、stringify 和返回结构
对外只有两个函数,但它们的输入形态和返回分支比最小示例多。先把签名和返回结构列全,后面排查才有落点。
parse(path, options?):只接受文件路径,不接受配置字符串、Buffer 或 URL。它的返回分四种情况:
- 不传
options:返回入口文件var的普通对象,其他作用域不输出。 { ir: true }:返回{ data, ir },ir是纯 JSON 可序列化的中间表示。{ json: true }:返回格式化好的 JSON 字符串,缩进 2 空格。- 两个都传:走
json分支,返回字符串,ir被忽略;未知选项直接忽略,仍返回对象。
import { parse } from "./VarJson/src/index.ts";
const data = await parse(entry); // 普通对象
const pair = await parse(entry, { ir: true }); // { data, ir }
const text = await parse(entry, { json: true }); // JSON 字符串
const same = await parse(entry, { ir: true, json: true });
console.log(typeof same);
// string —— json 优先
IR 的结构:顶层四个键 path、imports、scopeOrder、scopes。imports 是 { raw, alias } 的数组;scopeOrder 是作用域名的求值顺序;scopes 按名字索引,每个作用域有 name、kind、fields,字段的 value 是节点对象,常见 kind 有 literal、array、object、ref。
console.log(Object.keys(ir));
// [ 'path', 'imports', 'scopeOrder', 'scopes' ]
console.log(ir.scopeOrder);
// [ 'tops', 'var' ],有自定义作用域时会排在最前
console.log(JSON.stringify(ir.imports));
// [{"raw":"./base.vjson","alias":"base"}]
console.log(JSON.stringify({ kind: "literal", value: 1 }));
// {"kind":"literal","value":1} —— 字段值就是这种节点
IR 的价值在于保住「来源」:普通对象只有最终值,IR 还知道哪个字段来自哪个文件、哪一段是引用。需要可逆编辑时用它;只消费最终配置时不要多拿这一层,因为它比结果大得多,也会把内部节点形状暴露给你的代码。
stringify(input):接受四种输入,行为差别很大。
- 运行时 IR(
parse({ ir: true })拿到的ir):还原import和&引用,接近原始源码。 - IR 的 JSON 副本(经过
JSON.parse(JSON.stringify(ir))):同样能还原,函数会先识别这种形态再转回 IR。 - 普通对象:只生成
var = { ... }字面量,不生成 import、不生成引用、不保留来源。 - 数组或原始值:包成
var = { value = ... },数组本身作为值写入。
stringify([1, 2]);
// var = {
// value = [
// 1,
// 2
// ]
// };
stringify(42);
// var = {
// value = 42
// };
所以「对象 → 配置文本」和「IR → 配置文本」不是同一件事。前者是一次拍平,适合生成最终配置;后者才适合做可逆的源码编辑。需要可逆,就先 parse({ ir: true }),再 stringify(ir),不要从 data 出发。每次解析都是独立会话,结果经过深拷贝,修改返回对象不会污染下一次解析。
坑一:相对路径不是相对调用方
README 的示例写 parse("./app.vjson"),看起来像相对当前脚本。实际不是。源码里的路径解析函数 toAbs 用的是 import.meta.dirname,也就是 src/common.ts 所在目录;只有拿不到 dirname 的老环境才退回 process.cwd()。
我做了个对照实验:项目根目录和 src 目录各放一个同名 t-cwd.vjson,根目录那份写 from = "cwd",src 那份写 from = "src",然后调用 parse("./t-cwd.vjson")。结果是:
{"from":"src"}
也就是说,相对路径被解析到了库源码目录,不是调用方目录。这个行为在 Node 22 以下没有 import.meta.dirname 时会变,标为待确认。稳妥做法永远传绝对路径,或者用 fileURLToPath(new URL("./app.vjson", import.meta.url)) 生成绝对路径。文件内部的 import "./base.vjson" 是相对当前 .vjson 文件解析的,这一点和常见模块系统一致。
parse("./relative.vjson") 的默认基准。它跟着库文件位置走,你把库拷到别处、换 Node 版本、换打包方式,结果都可能变。入口路径一律用绝对路径。静默失效与报错原文:输入、实际结果、为什么
VarJson 的失败分两半:一半会抛异常,错误信息还算具体;另一半根本不报错,只是把你的字段悄悄丢掉或换成别的值。先看后半边,因为它们在生产环境里更常见。
| 输入 | 实际结果 | 为什么 |
|---|---|---|
stringify({ "a-b": 1, ok: 2 }) | a-b 直接消失,只剩 ok = 2 | 顶层键必须是合法标识符,带连字符的键不写,也不报错 |
stringify({ nested: { "x y": 3 } }) | nested = {} | 嵌套对象里的非法键同样被丢掉,父对象仍然保留 |
stringify({ a: NaN, b: Infinity }) | a = null, b = null | 非有限数字无法写成字面量,降级为 null |
stringify({ c: undefined, d: () => 1 }) | c = null, d = null | 未定义值和函数都不属于可表达的配置值,统一降级 |
parse<Broken>(entry),Broken 里有不存在的字段 | 访问该字段得 undefined | 泛型只是类型断言,运行时不校验,字段缺失也不会抛错 |
parse("./app.vjson"),文件在调用方目录 | 读到库源码目录的同名文件,或直接报 [Path Error] | 相对路径按 src/common.ts 所在目录解析,不是调用方目录 |
a = 1 + 2 | 抛 [Syntax Error] Operators are not supported | 语言没有运算符,所有计算必须放在生成配置的代码里 |
同一作用域写两个 a | 抛 [Syntax Error] Duplicate field in same scope: a | 不允许后者覆盖前者,避免覆盖顺序变成隐式规则 |
| 入口文件不存在 | 抛 [Path Error] No file found at this path | 先把绝对路径打印出来,确认文件真的在那个位置 |
前六行都不会让进程崩掉,只会让配置少字段或值变形。最典型的是泛型:README 说 parse<T> 用来标注返回类型,还建议超过约 1500 字符时显式写 T、「不要依赖自动推导」。但源码里没有类型级推导,T 默认就是 Record<string, unknown>,传什么就断言成什么,运行时不校验。这句「不要依赖自动推导」容易让人以为存在自动推导,实际是「没有推导,自己写类型」,标为待确认。
type Broken = { missing: string };
const broken = await parse<Broken>(entry);
console.log(String(broken.missing));
// undefined —— 没有校验,也没有默认值
后三行是显式错误,反而好处理:错误信息里带了字段名或原因,照着排查表走就行。真正要防的是前六行,所以解析之后必须自己检查关键字段,不能把泛型当成 schema。
组合用法:parse 结果怎么接同步流程,stringify 往返丢什么
parse 是异步的,返回 Promise。正确的接法是「启动时 await 一次,之后全程用普通对象」:在应用入口把配置读出来,传给同步的初始化函数、路由表、数据库连接参数。不要让同步函数内部再 await parse,也不要在每次用到配置时重新解析,那会把一次 IO 变成多次,还会让配置在运行中悄悄变化。
// 启动阶段:只解析一次
const cfg = await parse(entryPath);
// 之后都是同步逻辑,cfg 就是普通对象
const routes = buildRoutes(cfg);
const pool = createPool({ host: cfg.host, port: cfg.port });
// 修改返回对象是安全的:每次 parse 都是独立会话
cfg.debug = true;
普通对象还有一个好处:它能直接 JSON.stringify、能浅合并、能作为参数传给任何函数,不需要再经过 VarJson。VarJson 只在「读多文件配置」这一步出现,读完之后它就退场了。
反过来,stringify(data) 不是无损的。把对象写成文本再读回来,能保住普通键、字符串、有限数字、布尔、null、数组和嵌套对象;保不住的东西有四类:非标识符键、NaN 和 Infinity、undefined、函数。实测一次往返:
const original = {
"a-b": 1, ok: 2, n: NaN, u: undefined,
nested: { "x y": 3, keep: 4 },
};
await fs.writeFile(file, stringify(original), "utf8");
console.log(stringify(original));
// var = {
// ok = 2,
// n = null,
// u = null,
// nested = {
// keep = 4
// }
// };
console.log(JSON.stringify(await parse(file)));
// {"ok":2,"n":null,"u":null,"nested":{"keep":4}}
原来的 a-b、x y 两个键没了,NaN 和 undefined 变成 null。所以「对象 → 配置 → 对象」只适合生成最终配置,不适合当作持久化格式。要保住来源和引用,必须走 IR:parse({ ir: true }) 拿 ir,再 stringify(ir),这条路径不经过普通对象,也就不会触发这些降级。
如果配置的前半段来自另一种文本格式,也可以把对象当交接点:先用别的解析器得到普通对象,再交给 stringify 生成 .vjson。同组的 CompactProfile 就是这种角色——它把一段紧凑文本算成对象,VarJson 再把对象写成可导入的配置文件;两者没有代码依赖,只有对象这一层接口。
完整小项目:从空目录到能跑的配置加载器
VarJson 没有发布到 npm,所以这个小项目从克隆仓库开始。目标是一个三文件的加载器:两份 .vjson 负责配置,一个 loader.mjs 负责读、校验和覆盖。
git clone https://github.com/Deepl-ysp/VarJson.git
cd VarJson
mkdir demo
demo/base.vjson 只放公共事实,var 留空,表示这份文件不直接作为入口:
tops = {
host = "localhost",
port = 8080,
secrets = { token = "s3cr3t" }
};
var = {};
demo/app.vjson 是入口文件,通过别名 base 引用公共字段:
import "./base.vjson" as base;
var = {
host = &base.host,
port = &base.port,
token = &base.secrets.token,
endpoint = "http://localhost:8080",
features = ["a", "b"]
};
demo/loader.mjs 的完整代码。入口路径用 fileURLToPath 转绝对路径,解析后检查必填字段,最后做环境变量覆盖:
import { fileURLToPath } from "node:url";
import { parse } from "../src/index.ts";
const entry = fileURLToPath(new URL("./app.vjson", import.meta.url));
const cfg = await parse(entry);
const required = ["host", "port", "token"];
const missing = required.filter((k) => cfg[k] === undefined);
if (missing.length) throw new Error(`配置缺少字段: ${missing.join(",")}`);
const port = Number(process.env.PORT ?? cfg.port);
const final = { ...cfg, port, debug: port >= 8080 };
console.log(JSON.stringify(final, null, 2));
运行:
node --experimental-strip-types demo/loader.mjs
实际输出:
{
"host": "localhost",
"port": 8080,
"token": "s3cr3t",
"endpoint": "http://localhost:8080",
"features": [
"a",
"b"
],
"debug": true
}
几个设计点值得说明。第一,import 路径写 ../src/index.ts,是因为项目在仓库内部运行;如果以后发布到 npm,这一行会变成 from "varjson"。第二,app.vjson 里 endpoint 是重复写的字面量,不是用 host 和 port 拼出来的——语言没有字符串拼接,这是它的硬边界。第三,token 通过 &base.secrets.token 引用,而不是裸名,因为跨文件必须带别名。第四,环境变量覆盖放在解析之后,port 用 Number 转一次,避免字符串和数字混用。
再跑一次带环境变量的版本(PowerShell 用 $env:PORT=9000; node --experimental-strip-types demo/loader.mjs),port 和 debug 会变,endpoint 仍是文本里的旧值。这再次说明解析结果是快照:文本里写死的东西不会跟着 JS 侧覆盖一起变。
排查表:现象、原因和第一步
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
[Path Error] No file found at this path | 入口相对路径被解析到了库源码目录,不是调用方目录 | 把入口路径改成绝对路径,打印出来确认指向哪个文件 |
[Reference Error] This variable doesn't exist: b | 同作用域里引用了后面才定义的字段,或名字拼错 | 把被引用字段挪到前面;同作用域只能用前面已定义的裸名 |
[Reference Error] Cross-scope reference requires '&' | 想从 tops 或别的文件取字段,却写了裸名 | 按关系补 &tops.x 或 &alias.x;自定义作用域用 &!名字 |
[Syntax Error] Operators are not supported | 在值里写了加号、比较或条件表达式 | 把计算移到生成配置的代码里,文本里只留字面量 |
[Syntax Error] Duplicate field in same scope: a | 同一个作用域出现两个同名字段 | 去重或改名;不要指望后者覆盖前者 |
[Cycle Error] Circular reference detected | 字段直接或间接引用了自己,例如 a = &tops.a | 沿着引用链找回到自身的那一条,拆成中间字段 |
| 解析不报错,但对象里少字段 | stringify 丢了不合法的键或非有限值 | 检查键名是否是合法标识符,值里有没有 NaN、undefined、函数 |
边界与代价:它不解决什么
第一,它不解决环境变量。文本里写不了 process.env.PORT,也没有占位符替换。想按环境变化,要么生成不同的 .vjson,要么在解析后覆盖对象。
第二,它不解决合并策略。虽然能用 import 和引用把字段拼起来,但它没有「深度合并」「数组追加」「后者覆盖前者」这类规则。两个字段同名会直接报错,逼你显式决定用哪个。这是约束,不是功能缺失。
第三,它不做类型校验,也不做默认值。泛型只是断言,缺字段就是 undefined。第四,它不缓存。每次 parse 都重新读文件、重新求值,配置文件多或者调用频繁时要自己加缓存,并且想清楚什么时候失效。
第五,它只读文件路径。没有从字符串解析的入口,也没有远程加载,所以浏览器里不能直接用,除非你给它一个文件系统垫片。当前版本不依赖任何外部请求库,解析只读本地文件。第六,序列化有损:stringify 从普通对象出发会拍平来源信息,特殊键和非有限值会被丢掉或变成 null。需要可逆编辑就用 IR,不要用普通对象往返。
适合用
配置需要跨文件复用、字段之间有明确引用关系、希望最终产物是普通对象、团队能接受「没有运算和分支」的文本格式。比如基础配置加多环境覆盖、构建期生成配置、把公共常量抽成零件。
不适合用
需要在配置里做计算、需要按环境写条件、需要 schema 校验和默认值、需要浏览器直接加载、需要与 JSON/YAML 工具链互通。这些需求它明确不接,硬套只会把复杂度转移到外面。
自己验证:五个练习
- clone 仓库,按 README 的命令跑一次,确认
test/test.ts报错;再换成src/test/test.ts,看到 48 passed。 - 建两个
.vjson文件,一个放tops,一个用import和&alias取字段,打印结果,确认依赖文件的var不会出现在入口输出里。 - 把入口改成
parse("./app.vjson"),在src和项目根目录各放一份同名文件,验证它实际读了哪一份。 - 写一个
parse<Broken>,访问不存在的字段,确认得到undefined而不是类型错误。 - 先用
stringify往返一个带a-b键、NaN和函数的对象,记录丢了什么;再用parse({ ir: true })拿 IR 往返一次,对比两次文本是否保留了 import 和引用。
小结
选择它的判断标准很简单:配置是否需要跨文件复用、字段之间是否有稳定的引用关系、团队是否愿意放弃运算和 schema 校验。三个答案都偏向「是」,它才值得引入;只要有一个必须靠库内计算解决,就该换方案。
上一篇 CompactProfile 解决「一段文本怎么变成对象」,这一篇解决「多个文件怎么拼成对象」。下一篇 unireq 讲的是另一个独立问题:请求怎么发、错误怎么分类、超时和重试怎么控制。三个库可以各用各的,也能通过普通对象交接。