项目里有本地、预发、生产三套配置,每套都要写一遍主机名、端口、API 前缀。某次预发端口从 8080 改成 8081,两份文件改了,第三份漏了,联调时前端一直请求旧端口,日志里看不出任何异常。你想用 JSON 管这份配置,又发现它不能写注释,不能写 port = basePort + 80,多一个尾逗号还会直接报错。
CompactProfile 就是为这种「比 JSON 多一点点计算,又不想引入一门完整语言」的场景写的。它把一段形如 key=value 的文本解析成普通的 JS 对象,支持前后引用、字符串拼接、条件表达式和简单的成员访问,还能把对象写回同样的文本。这一篇讲清楚它到底能做什么、三个 API 怎么用、哪些坑不会报错但会把配置悄悄改坏。
事故现场:配置需要算一下,但不想写代码
先把需求摆出来。一个前端项目要生成接口地址,规则是:本地用 8000 端口,预发在基础端口上加 80,生产固定 8443;调试模式由端口是否大于等于 8080 决定;接口前缀统一为 /api。这段规则写在 JSON 里只能靠构建脚本二次加工,写在 JS 里又要把配置和逻辑混在一起,非开发人员不敢改。
用 CompactProfile 的写法是:
appName='shop',
basePort=8000,
port=basePort+80,
api={ prefix='/api', url='http://localhost:'+port+prefix },
debug=port>=8080,
mode=if(debug) 'dev' else 'prod'
它仍然是一段纯文本,没有函数、没有变量声明、没有 import。解析器按字段顺序逐条求值,前面的字段可以给后面的字段用。对配置来说,这个范围刚好:能算端口和地址,又不会让人在里面写业务逻辑。
它到底是什么,不是什么
从仓库源码看,它是一个纯 ESM 的 npm 包,没有运行时依赖,也没有文件读取、网络请求或环境变量读取。你给它一段字符串,它返回一个对象;你给它一个对象,它返回一段字符串。仅此而已。
这意味着它不负责「配置从哪里来」。文件读取、环境变量覆盖、多环境合并、密钥注入,都得由调用方自己完成。它也不做 schema 校验:字段少了、类型错了,它不会在运行时拦住你,只会在你访问到那个字段时返回 undefined。这是它最需要提前知道的一条边界。
parse、stringify、encodetags,以及可选的类型标注安装与第一次跑通
它是一个已发布到 npm 的包。本文实测时 npm 上的最新版本是 1.1.1,仓库里的 package.json 写的是 1.1.0,两者不一致,属于发布流程留下的版本号差异,标为待确认;下面的示例都跑在 npm 安装的 1.1.1 上。
mkdir cp-demo
cd cp-demo
npm init -y
npm install compact-profile
npm ls compact-profile
预期输出里能看到实际安装的版本:
cp-demo@1.0.0
└── compact-profile@1.1.1
建一个 demo.mjs,把刚才那份配置放进去:
import { parse, stringify, encodetags } from "compact-profile";
const text = `
appName='shop',
basePort=8000,
port=basePort+80,
api={ prefix='/api', url='http://localhost:'+port+prefix },
debug=port>=8080,
mode=if(debug) 'dev' else 'prod'
`;
const cfg = parse(text);
console.log("parsed:", JSON.stringify(cfg));
console.log("compact:", stringify(cfg));
console.log("pretty:\n" + stringify(cfg, { format: true, indent: 2 }));
本机 Node 24 下实际输出:
parsed: {"appName":"shop","basePort":8000,"port":8080,"api":{"prefix":"/api","url":"http://localhost:8080/api"},"debug":true,"mode":"dev"}
compact: appName='shop',basePort=8000,port=8080,api={prefix='/api',url='http://localhost:8080/api'},debug=true,mode='dev'
pretty:
appName='shop',
basePort=8000,
port=8080,
api={
prefix='/api',
url='http://localhost:8080/api'
},
debug=true,
mode='dev'
注意两个细节。第一,url 里的字符串拼接真的发生了,port 和同作用域的 prefix 都被替换成了值。第二,stringify 输出的引号风格和缩进由它自己决定,不需要你手工对齐。到这一步,基础闭环已经跑通。
API 全覆盖:五个具名出口和一个默认导出
包的公开出口是 parse、parseAs、stringify、encodetags、types,外加一个默认导出对象。README 重点只写了两个,剩下几个很容易被漏掉,但它们在真实项目里各有用处。下面按源码逐个过。
parse(text, type?):只接收字符串和可选的输出模式。第二个参数只认 "Object"(默认)和 "Array"。Array 模式返回的不是值的数组,而是「每个字段单独成对象」的数组,这一点和直觉不一样:
import { parse, types } from "compact-profile";
console.log(parse("a=1,b=2", types.Array));
// [ { a: 1 }, { b: 2 } ] —— 不是 [1, 2]
console.log(parse("user={name='Alice',age=30},n=user.name"));
// { user: { name: 'Alice', age: 30 }, n: 'Alice' }
console.log(parse(""));
// {}
为什么是这种形态?源码里 Array 模式执行的是 Object.entries(result).map(([k, v]) => ({ [k]: v })),每个键值对包成一个小对象,再放进数组。它适合把配置逐项喂给表格或表单,不适合当成纯值列表用。另外,运行时只判断第二个参数是不是 "Array";传 "Integer" 之类会被忽略,仍然返回对象,TypeScript 层才会拒绝这种写法。空字符串返回空对象,末尾多一个逗号也能容忍,单引号和双引号字符串都支持。
parseAs<T>(text, type?):parse<T>(text) 的函数式写法,把泛型放到调用位置,运行时走同一个实现。它返回的是断言后的类型,不做校验。
import { parseAs } from "compact-profile";
const cfg = parseAs<{ host: string; port: number }>(
"host='localhost',port=8080",
);
console.log(cfg.port + 1);
// 8081
stringify(obj, options?):第二个参数可以是布尔值,等价于 { format: true };也可以是对象 { format, indent },indent 默认 2。它把对象写成顶层 key=value 列表,把数组展开成其中每个对象的键值对,非对象元素直接忽略。字符串统一用单引号,并转义反斜杠、单引号、换行、制表符等控制字符。
import { stringify } from "compact-profile";
console.log(stringify({ a: 1, b: "it's" }));
// a=1,b='it\'s'
console.log(stringify([{ a: 1 }, 2, { b: 3 }]));
// a=1,b=3
console.log(stringify({ a: 1, b: { c: 2 } }, true));
// a=1,
// b={
// c=2
// }
console.log(JSON.stringify(stringify(42)));
// ""
最后一行是容易踩的空串:非对象输入(数字、字符串、null、undefined)统一返回 "",不抛错。另一个细节是键名不加引号,所以键里带等号、逗号或大括号会直接破坏结构,而带空格或中文反而能往返。这个差异下面用表列清楚。
encodetags:模板字符串标签,把 JS 值插进配置文本再解析。它的插值规则按类型分派,不是简单的字符串拼接:
- 数字、布尔:
String(v),直接变成字面量。 - 字符串:不加引号,会被当成标识符或引用,所以模板里必须自己写
'${host}'。 - 数组:自动带
[],元素里的字符串会自动加单引号,模板里不要再写一对方括号。 - 对象:用
stringify生成{k=v},自动带大括号。 null/undefined:写成null/undefined文本,后者解析成未定义引用。
import { encodetags } from "compact-profile";
const host = "localhost";
const port = 8080;
const tags = ["a", "b"];
const extra = { debug: true };
const text = encodetags`host='${host}',port=${port},tags=${tags},extra=${extra}`;
console.log(JSON.stringify(text));
// {"host":"localhost","port":8080,"tags":["a","b"],"extra":{"debug":true}}
它用的是模板的 strings.raw,所以反斜杠转义不会先被 JS 处理,写路径时要留意。返回类型固定是 EncodeObjectResult,没有编译期推导,字段类型只能靠你自己标注。
types:一个冻结的常量表,共 23 个键。它混了两类东西:输出模式 Object、Array,以及解析器内部用的节点名,比如 Integer、Pointer、FormulaAdd、Conditional。对使用者有意义的只有 types.Array 和 types.Object;其余常量是给 AST 和类型推导用的,不是「把值转成某种类型」的开关。写 parse(text, types.Integer) 不会把字符串转成整数。
import { types } from "compact-profile";
console.log(Object.keys(types).length);
// 23
console.log(Object.isFrozen(types));
// true
console.log(types.Object, types.Array);
// Object Array
默认导出:import CompactProfile from "compact-profile" 拿到的是一个类对象,静态成员就是上面五个 API:types、parse、parseAs、stringify、encodetags。实例上有 type = "CompactProfile"。它的 instanceof 被改写成了只检查 type 字段,所以一个普通对象只要写了 type: "CompactProfile" 也会判定为 true。这不是 bug,源码注释明确说明不要求真实实例。
import CompactProfile from "compact-profile";
console.log(Object.keys(CompactProfile));
// [ 'types', 'parse', 'parseAs', 'stringify', 'encodetags' ]
console.log({ type: "CompactProfile" } instanceof CompactProfile);
// true
风格上,具名导入更常见;默认导出适合需要统一命名空间或做能力检测的场景。两种写法引用的是同一批函数,不存在两套实现。
静默失效:输入、实际结果和原因
这个库最需要提前知道的特点是「宽松求值」:很多不认识的写法不会抛异常,而是退化成一个空对象、undefined 或 NaN。下面这些结果都在本机跑过,表里写的是实际输出,不是推测。
| 输入 | 实际结果 | 为什么 |
|---|---|---|
parse("a=True") | { a: undefined },JSON 打印成 {} | 布尔只认小写 true / false;True 被当成未定义标识符,不报错 |
parse("a=0x1f") | {},连 a 都没有 | 数值字面量只支持十进制,十六进制不在规则内,整段退化为空 |
parse("a=1;b=2") | {} | 分号不是分隔符,解析器切不出合法字段,也不报语法错误 |
parse("// hi\na=1") | { "// hi\na": 1 } | 没有注释语法,注释行被并进键名 |
parse("b=a+1,a=1") | b 是 NaN,JSON 里显示为 null | 按顺序求值,算 b 时 a 还不存在;undefined 参与加法得 NaN |
parse("x=missing") | x 是 undefined | 未定义引用不抛错,只求值为 undefined |
parse("a=1", "Integer") | 仍返回 { a: 1 } | 第二个参数运行时只认 "Array",其他值被忽略;类型层才会拒绝 |
stringify({ "a=b": 1 }) | a=b=1,再解析得 {} | 键不加引号,键里的等号把字段切成两半 |
stringify({ "a,b": 1 }) | a,b=1,再解析得 { b: 1 } | 逗号是字段分隔符,前半段被当成一个残缺的键 |
stringify(42) | 空字符串 "" | 非对象输入直接返回空串,不抛错 |
encodetags`name=${name}` | { name: undefined } | 字符串插值不加引号,生成 name=Alice,Alice 被当成未定义引用 |
这些行里最危险的是整段返回 {}。它看起来像「配置没读到」,实际是语法没被识别;而下一条代码往往只是拿不到字段,直到运行时才暴露。所以解析之后先检查关键字段是否存在,再往下走,这一步不能省。
和静默失效相对的是「会抛错」的一类。同一作用域出现重复键时,解析器直接抛异常,而不是让后者覆盖前者:
parse("user={name='Alice'},pair={user.name,user.name}");
// Error: CompactProfile: duplicate key "name" in the same scope
README 的 10.3 节写「同一对象里键名重复时后者覆盖前者」,和实际运行结果不一致。以代码为准:重复键是错误,不是覆盖。这个差异其实更安全,因为覆盖会让「两个文件合并后谁生效」变成隐式规则;直接报错能逼你改名字或去掉重复字段。标为待确认,因为不确定作者是否打算保留旧文档里的行为。
类型推导:小配置的甜头,大配置的坑
这个库真正区别于普通 eval 式配置解析的地方,是它的 TypeScript 类型层。当配置文本是字面量时,parse 能在编译期推导出每个字段的类型,并在重复键时给出 DuplicateKeyError。仓库自带类型级测试,用 Expect 和 Equal 断言推导结果,tsc 能通过。
但这份甜头有明确上限。源码注释写着:字面量超过约 1500 字符,编译期推导可能爆 TS2589(类型实例化过深)。实际项目里更常见的做法是给文本标注宽类型 string,再手写一个 interface,用 parse<Config>(text) 注入外部类型。
interface AppConfig {
host: string;
port: number;
}
const text: string = readFileSync("./app.conf", "utf8");
const cfg = parse<AppConfig>(text);
cfg.host.toUpperCase(); // 编辑器里有补全
要特别强调:这里的 <AppConfig> 是类型断言,不是运行时校验。配置里少一个 host,编辑器不会报错,运行时 cfg.host 就是 undefined,然后 .toUpperCase() 抛错。类型层只负责让你写得舒服,不负责保证数据正确。想要运行时校验,得自己写检查函数,或者换用带 schema 的配置方案。
另外,仓库 README 只介绍了 parse 和 stringify,没有提 parseAs 和默认导出对象;这些在源码里是真实存在的。文档覆盖不全不算矛盾,但读 README 时会漏掉 API,标为待确认。
完整小项目:从空目录到能跑的配置加载器
前面讲的都是片段,这里把整条链路走一遍:读文件、解析、校验必填字段、按环境覆盖,最后打印结果。目录结构只有三个文件:
cp-loader/
├── app.conf
├── loader.mjs
└── package.json
初始化并安装:
mkdir cp-loader
cd cp-loader
npm init -y
npm install compact-profile
app.conf 放配置文本。注意字段顺序:host 必须写在 apiUrl 前面,因为解析器按顺序求值,后面才能引用前面。
host='localhost',
basePort=8000,
port=basePort+80,
prefix='/api',
apiUrl='http://'+host+':'+port+prefix,
debug=port>=8080
loader.mjs 完整代码如下。它做了三件事:用绝对路径读文件、解析后检查必填字段、把环境变量覆盖放在解析之后而不是塞进文本里。
import { readFileSync } from "node:fs";
import { fileURLToPath } from "node:url";
import { parse } from "compact-profile";
const file = fileURLToPath(new URL("./app.conf", import.meta.url));
const text = readFileSync(file, "utf8");
const cfg = parse(text);
const required = ["host", "port", "apiUrl"];
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 loader.mjs,实际输出:
{
"host": "localhost",
"basePort": 8000,
"port": 8080,
"prefix": "/api",
"apiUrl": "http://localhost:8080/api",
"debug": true
}
这段代码里有几个决定是刻意的。第一,parse 只接收文本,所以读文件必须自己写,路径用 import.meta.url 转绝对路径,避免工作目录一变就找不到。第二,必填字段检查不能省:库对缺失字段不报错,只给 undefined,如果直接拿去拼 URL,会得到 "http://undefined:8080" 这种脏值。第三,环境变量覆盖放在解析之后,因为文本里根本写不了 process.env;把覆盖逻辑留在 JS 里,配置文本就能保持纯声明式。
还可以把 PORT=9000 传进去再跑一次:PORT=9000 node loader.mjs(Windows PowerShell 用 $env:PORT=9000; node loader.mjs),port 和 debug 会跟着变,而 apiUrl 仍然是文本里算好的旧值。这不是 bug,是「覆盖发生在解析之后」的直接结果;如果希望 URL 也跟着变,就在覆盖后重新拼一次。
组合用法:产物怎么接进别的流程
parse 的返回值就是一个普通对象,没有类实例、没有隐藏字段、没有原型污染。这意味着它可以立刻做三件事:JSON.stringify 落盘、和别的配置做浅合并、作为参数传给同步函数。配置加载通常是异步的,但一旦 parse 返回,后续就是纯同步逻辑,不需要再 await。
如果配置还需要跨文件组装,可以把它交给同组的 VarJson。两者的衔接点是普通对象:CompactProfile 负责「一段文本算出对象」,VarJson 的 stringify 负责「对象写成 .vjson 文本」,再由 VarJson 的 parse 读回来。这条链路在本机跑过:
import fs from "node:fs/promises";
import { fileURLToPath } from "node:url";
import { parse } from "compact-profile";
import {
parse as vparse,
stringify as vstringify,
} from "./VarJson/src/index.ts";
const cfg = parse("host='localhost',port=8080,features=['a','b']");
const file = fileURLToPath(new URL("./generated.vjson", import.meta.url));
await fs.writeFile(file, vstringify(cfg), "utf8");
console.log(JSON.stringify(await vparse(file)));
// {"host":"localhost","port":8080,"features":["a","b"]}
这段需要先有 VarJson 的源码(它没有发布到 npm),所以跨库示例只在仓库目录里跑得通。它说明的是边界:两个库没有 API 依赖,只通过「对象」和「文本」交接;你完全可以不用 VarJson,把对象直接写成 JSON。选哪个取决于下一步要不要引用、导入和多文件组装。
排查表:现象、原因和第一步
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
某个字段是 undefined,程序不报错 | 引用了不存在的名字,或大小写写错 | 在文本里搜这个名字,确认它在前面的字段里已经定义,且 true、false、null 都是小写 |
解析直接抛 duplicate key | 同一作用域出现两个同名键,自动键也算 | 搜 key= 和对象里的裸标识符,注意 user.name 的自动键只取最后一段 name |
数字字段变成 null 或 NaN | 引用了后面才定义的字段,undefined 参与了加法 | 把被引用字段挪到前面;在控制台直接打印对象,不要只看 JSON |
模板插值得到 undefined | encodetags 里的字符串没有加引号 | 检查 ${变量} 两边是否有单引号,生成的是 name=Alice 还是 name='Alice' |
整段配置变成空对象 {} | 用了分号、十六进制、注释等不支持的写法 | 从整段文本里二分删减,先定位到最小可复现片段,再改写法 |
| TypeScript 类型对,运行时却崩 | parse<T> 只是类型标注,不校验数据 | 在解析后加字段存在性检查;不要用类型代替运行时校验 |
编译报 TS2589 | 字面量太长,类型推导递归过深 | 把文本改成 string 类型变量,手写 interface 后用 parse<Config> |
边界与代价:它不解决什么
把「不解决」写清楚,比列功能更重要。CompactProfile 不解决文件加载,不解决环境变量,不解决多环境合并,不解决默认值,不解决 schema 校验,不解决密钥管理。它也不支持函数调用、空值合并、可选链、正则字面量、模板字符串、赋值运算符、循环,以及二进制和八进制字面量。你需要这些能力时,应该换工具,而不是在配置里绕。
序列化方向也有代价。stringify 对非对象返回空字符串;数组只展开对象元素;NaN 和 Infinity 会被写成字面量 NaN、Infinity,再解析时又变成未定义引用;循环引用对象会直接爆栈。它也不会给键加引号,键名里带特殊字符时不保证能原样往返。对象里有日期、函数、Symbol 时,结果更接近「丢掉」而不是「序列化」。
还有一点容易被忽略:它解析的是你自己写的文本,不执行任意代码,所以不需要沙箱;但它也不对输入做资源限制,超大文本或超深嵌套仍然会消耗内存和栈。不要把它当作用户输入的安全边界,它只是配置解析器。
适合用
构建期配置、自己掌控的运维脚本、需要少量计算和拼接的模板参数、希望在前端和后端共用一份小配置。文本短、字段稳定、团队能接受「宽松求值」。
不适合用
终端用户直接编辑的配置文件、需要精确错误定位的表单、需要 schema 校验和默认值注入的大型配置、需要注释和标准 JSON 互操作的场景。这些需求它都不接。
自己验证:五个练习
- 安装后解析一份三层嵌套配置,打印对象,再用
stringify写回,比较两次文本的差异。 - 构造一个重复键,确认它抛出
duplicate key,再对照 README 10.3 节的「后者覆盖前者」,记录这个待确认差异。 - 分别用
encodetags的有引号和无引号写法,观察JSON.stringify的结果为什么一个是空对象。 - 构造
b=a+1,a=1,在控制台直接打印对象,确认b是NaN而不是null。 - 把配置文本从字面量改成
const text: string,观察编辑器补全从精确字段退化为宽类型,再手写 interface 用parse<Config>找回补全。
小结
下一篇讲 VarJson。CompactProfile 解决的是「一段文本怎么变成对象」;VarJson 解决的是「对象怎么由多个文件和多个作用域拼起来」。如果你正被多环境配置的重复字段折磨,可以直接跳到下一篇;如果你只需要解析一段小配置,这一篇的工具已经够用。