别名配置
类型定义
文件级只解释这八个 $ 开头的键;其余 $xxx 不会被当作别名,也不参与合并,保留给其他工具存放配置。字符串里的 ${xxx} 由变量机制展开,未声明的名字原样留给 shell。
别名对象
Key 命名规则
- key 不能包含
@或.,违规则该条目被静默忽略 - 支持中文 key 名
- 支持嵌套分组(object),通过
.分隔符访问
系统字段
含 $cmd 的 object 是别名叶子节点。只有 $cwd / $mode / $private / $clone 而没有 $cmd 的 object 是带继承属性的分组,本身不可执行。
工作目录 cwd
三级继承:文件级 → 分组级 → 别名级,越靠近别名优先级越高。支持 ~;相对路径以别名文件所在目录为基准解析,与你在哪个目录敲 byk 无关。不写 $cwd 时用调用时的工作目录。
文件级 $cwd 会被所有子别名继承。若某个别名需要回到“敲下 byk 时”的目录,把它的 $cwd 写成 "${work_dir}":
${work_dir} 在扫描期就展开为绝对路径,写它等同于在配置里直接写绝对路径,因此不再参与相对路径解析。它指当前这次 byk 进程启动时的目录:别名 A 在自己的 $cwd 里调用 byk B 时,B 看到的 ${work_dir} 是 A 的工作目录。
执行方式
$mode 决定别名怎么跑,三态互斥,默认 normal。
执行前 byk 会往 stderr 打两行提示:来源(文件.key 与落地目录)和解析后的最终命令。
走 stderr 而不是 stdout,是因为这两行是给人看的旁白,不该混进可以被管道消费的数据:
byk build > log.txt、byk build | grep error拿到的只有命令自己的输出;- stderr 不是终端时(被
2>重定向、CI、编辑器任务)这两行干脆不打; - 想连终端上也保持安静,才写
$mode: "silent"。
interactive 适合有副作用的命令:
$mode 支持三级继承:文件级 → 分组级 → 别名级,越靠近别名优先级越高。
交互和静默是互斥的两种形态:交互必须让用户看清要确认什么,所以 silent 只是让 byk 闭嘴,
不会跳过任何确认步骤——需要确认就写 interactive。
递归保护
$cmd 是任意 shell 字符串,它完全可以再调用 byk —— 包括解析回自己。把 add 的 $cmd 写成
byk add,每一层都会再展开同一个别名;每层都是独立进程,没有栈溢出这种天然上限,
只有进程数一路往上涨,直到机器吃不下为止。
byk 为此给调用链留了标记:执行别名前把 文件.key 压进环境变量 BYK_ALIAS_STACK
(逗号分隔)交给子进程。下一层发现自己已经在链路上,就报错退出:
报的是完整链路而不只是首尾两个名字,因为「谁绕回来的」才是要定位的东西。
链路超过 32 层同样拦住:这一层兜底是给标记被清空的场景准备的(env -i byk build、
外部包装器),标记传不下去,只能靠深度止损。
刻意自调用(FOO=1 byk build、sudo byk serve)需要显式放行,两种写法等价:
放行只取消「同一别名重入」这一项检查,深度上限照样生效。
$recursive 只对当前别名生效、不继承。$mode: "silent" 也压不住这条错误——
它本来就是用来说明「命令为什么卡住」的。
描述文本
$description 替代帮助页里默认显示的命令文本,仅对当前别名生效、不继承。
未设置时显示命令本身:
只有在没有描述时,解析后的 $cwd 才会以括号追加在命令后面;有描述时只保留这一行摘要,不再显示工作目录。
PATH 目录
$paths 在执行别名前把目录前置到 PATH,让别名可以直接调用这些目录下的可执行文件。
仅支持文件级,所有子别名自动继承;写在分组里会被忽略。
- 相对路径以配置文件所在目录为基准解析,
~会展开 - 不存在的目录静默跳过,不会出现在子进程的
PATH里 - 另外,别名运行时 byk 会自动把工作目录下的
node_modules/.bin追加到PATH前面;声明了$deps.pip/$deps.npm时,依赖目录里的 venv bin /node_modules/.bin也会一并前置——这些都不需要自己写进$paths $paths的顺序就是PATH里的优先级顺序,越靠前越优先
依赖
$deps 声明一个别名文件需要的东西——资产文件,以及可选的 pip 包与 npm 包——byk 负责把它们装到这个文件的专属目录:
两种作用域同一套规则,只是根不同:全局的依赖留在 ~/.byk,局部的依赖跟着项目走(删项目即删依赖,不占全局空间)。局部安装时会自动写一个 .byk/deps/.gitignore(内容 *),所以下载产物不会出现在 git status 里。
声明本身不触发任何网络行为,安装是显式动词:
包与文件条目一起安装。 $deps.pip 与 $deps.npm 每次 ..deps install 都会执行——由 pip / npm 自己判断是否最新——所以 --force 只影响文件条目。它们不记进 .byk-deps.json:从声明里删掉某个包不会卸载它,想清空整个目录用 ..deps uninstall。..deps status 把每个包列为 pip:<规格> / npm:<规格>;pip 的 URL / VCS 直接引用显示为 unknown,因为本地拿不到包名来比对。files 可以省略,所以声明里可以只有包。
base 是 clone 唯一会改写的字段。 落盘的别名文件住在 ~/.byk/alias/,它没有自己的位置信息,所以相对路径只有在 ..clone 那一刻才能解释。写成什么形态取决于来源,而形态本身就决定了资产怎么取:
两条路互不越界:远程 clone 只会写出 URL 形态,所以从网上拿到的别名文件读不了本机文件。这不是靠检查挡住的,而是它根本拿不到本地路径这种写法。
补 base 的规则两边一致,只是基准和产物不同:没写就按源文件所在目录补上,写了相对形态(.、../、sub/dir)就相对源文件解析,写了绝对地址(URL 或路径)就原样保留,只补结尾的 /。基准一律是源文件所在目录,不是落盘的目标目录——files 里的相对路径是作者照着源文档写的,~/.byk/alias/ 旁边没有那些文件。
补写 base 会让 clone 重新序列化整份文档(键按字典序重排)。既没有 $deps 也没有 $clone 的文件不受影响,仍是字节级副本;base 已经等于将要写入的值时也不改写,重复 clone 不会产生 diff。clone 不接受 base 里的变量。 clone 期没有变量表,"base": "${CDN}" 求不出值,猜一个写死只会把作者意图烧成假地址,见到它会直接失败并提示改源文件。(读取期更宽:..deps i 会先展开变量,所以手写的 ${CDN} 只要展开成绝对地址仍然能装。这条限制只针对 clone,编辑器里的 schema 按 clone 的口径提示。)base 定位就是"程序写的字面量":clone 冻结一次,之后谁读都一样。
本地 base 是不可移植的:它写的是这台机器上的绝对路径,换机器就失效。本地依赖的定位就是"本机开发工具",别指望把它分享出去还能用。
Windows 上还有一条:/sub 这种没有盘符的根路径挂在"当前盘"上,换个工作目录就指向别处,所以只认相对路径和盘符开头的绝对路径(C:/share/),/sub 直接报错。
本地条目按源文件的 mtime 判新旧:源比装好的那份新就重装,所以改完本地产物再跑一次 ..deps i 就生效(想无条件重来用 --force)。URL 条目没有这个概念——同一个地址就是同一份内容,keep 永远安全。源文件不存在时报错并给出路径,不会安静地报 up to date。
别名里用 ${deps_dir} 引用专属目录。这个目录由 byk 托管:安装时按声明同步文件条目,别往里手放需要长期保存的东西。
--check 只校验这份声明本身(能不能解析、落点是否冲突、相对 src 有没有 base、包条目是否非空字符串);缺哪条、旧没旧要看 ..deps status。
$var、$paths 与 $deps 自身都会先经过变量替换,可以用 ${version} 之类的自定义变量拼 URL。
链接文件的依赖:声明跟着目标文件走,安装位置跟链接文件的 key 走——全局链接落到 ~/.byk/deps/@@<链接文件名>/,局部链接落到它所在项目的 .byk/deps/@<链接文件名>/。详见 单链接。
变量
变量来自两处,合并成一张表,扫描期一次性替换完成。内置变量只有目录这一类,名字一律以 _dir 结尾、值都是绝对路径:
同名时文件声明覆盖内置——显式写下的值,就是你预期的那个值。
语法统一为 ${name},name 为 [A-Za-z_][A-Za-z0-9_]*(与 shell 标识符一致):
裸 $byk_dir 没有结束符,$byk_dirfoo 到底是变量 byk_dirfoo 还是 byk_dir 接上 foo,无法判断。${byk_dir}foo 没有这个歧义——这也是它和 shell 写法一致的原因。
引号自己负责:值里含空格时按 shell 规则自己包引号,byk 不会替你加。
三个目录别混淆:
不要用 shell 的 $PWD 找调用目录:byk 用 $cwd 作为子进程的工作目录启动 shell,$PWD 会被重置成 $cwd,永远拿不到调用时的目录;Windows 的 %CD% 同理。需要调用目录时用 ${work_dir}。
调用示例
别名文件
byk 读取两个位置:全局目录 ~/.byk/alias/ 与当前工作目录(不递归)。
文件命名规范
合法字符:字母、数字、-、_、中文。
禁止字符:.、@、/、空格。
非法命名的文件(如 aaa.bbb.byk.json)会被静默跳过,不报错。
目录结构
单链接
根是只含一个路径的数组时,这个文件是链接文件:指向另一个别名文件的指针:
含义是「放弃自己的身份」:@/@@ 前缀、key、默认优先级留在链接文件上,别名内容与一切声明都来自目标文件,相对路径也以目标文件所在目录为基准。所以同一份 bundle,直接扫描和通过链接,行为完全一致。
目标缺失、JSON 损坏、数组为空时,只跳过该文件,其他别名照常可用。
优先级
所有参与合并的文件共享一个 key 空间,优先级高的覆盖低的。
默认值
所以「就近优先」:项目里的文件自动覆盖全局同名别名,进目录就能 byk <key>,不用写任何声明。
同优先级文件按文件名字母序加载,匿名文件 .byk.json 排在同级最后,后加载的覆盖先加载的。所以同一目录里若 a.byk.json 与 .byk.json 都有 build,生效的是 .byk.json 那份。
当 cwd 恰好是 ~/.byk/alias/ 时,那里的文件同时属于「当前目录」和「全局目录」。它会以两个身份被扫描(@f 与 @@f 都能精确调用),但只按全局身份参与一次合并,不会被合并两遍。
自定义顺序
需要压过同目录的其他文件时,才需要写数字:
$priority 只负责同名冲突时的排序;小于 0 的值按 0 处理。是否进入合并空间由 $private 决定。
$priority 是保留字段,不会被当成别名 key。不写时当前目录为 1、全局为 0。
可见性
$private: true 让一段别名不进入合并空间,只能通过精确语法 @文件.key / @@文件.key 调用。
它和 $cwd / $mode 一样支持三级继承:文件级 → 分组级 → 别名级,越靠近别名优先级越高;子级写 false 可以重新暴露。
byk shared 照常可用;byk scratch.deploy 找不到,只能 byk @run.scratch.deploy。
整个文件都不进合并空间时,把 $private 写在文件根:
$private 只影响合并空间;精确调用始终可用,包括 private 分组里的别名。
克隆
$clone: false 把一段别名标成"自己的":..clone 永远不复制它。它只是复制期的标签,不影响合并空间、执行、补全或任何其他查找。
和 $private 一样支持三级继承:文件级 → 分组级 → 别名级,越靠近别名优先级越高;子级写 true 可以重新暴露。
clone 这个文件只会得到 shared.whoami,deploy 被剔除。如果剔除后什么都不剩,..clone 会直接拒绝、不落盘。这个标记本身也不会出现在副本里。
$private 和 $clone 相互独立:既要避开合并空间、又要避开 clone 副本时,两个都写。
$clone 只约束 byk ..clone。cp、git、用其他方式拉取文件仍然能看到原始字节——它是声明式约定,不是加密。
精确执行语法
约定:
- 只做文件路由,不做 fallback
- 文件不存在 →
Alias file not found: @release(全局报@@release) - 文件存在但无法加载 →
Alias file cannot be loaded: @release,附原因并提示byk --check - 文件存在但 key 不存在 →
Alias key not found in file @release: build - 路径段以
$开头 →Not an alias (reserved $ field);$字段是保留字段或自定义元数据,不是别名 - 以上都以退出码 1 结束