Nushell 脚本评审检查清单
用于评审 Nushell 脚本的综合检查清单。按优先级顺序逐项检查。
---
1. 安全(关键)
22 项代码注入
- [ ] 不得对不可信输入使用
nu -c $variable内置来源与改动说明
- [ ] 不得在
source $variable中使用运行时路径(必须为const)内置来源与改动说明
- [ ] 不得
run不可信的.nu脚本路径;run目标必须是解析期常量内置来源与改动说明
- [ ] 不得将插值的用户输入传给
^sh -c、^bash -c或^cmd.exe /C内置来源与改动说明
- [ ] 不得在
run-external中使用用户可控的命令名内置来源与改动说明
路径安全
- [ ] 用户提供的既有路径通过严格展开 +
path relative-to校验;不做字符串前缀包含性检查内置来源与改动说明
- [ ] 不得在没有路径穿越防护的情况下直接
open $user_input内置来源与改动说明
- [ ] 检测并拒绝用户路径中的
..序列内置来源与改动说明
- [ ] 文件操作强制限定基础目录内置
来源与改动说明
凭据处理
- [ ] 源代码中不含硬编码机密内置
来源与改动说明
- [ ] 凭据用
with-env限定作用域,而不是直接设置到$env内置来源与改动说明
- [ ] 机密从文件/stdin 读取,而不是作为命令行参数传递内置
来源与改动说明
- [ ] 凭据不经
print记录日志,也不写入非安全文件内置来源与改动说明
破坏性操作
- [ ]
rm操作校验目标路径(不是/,不是$nu.home-dir)内置来源与改动说明
- [ ] 来自用户输入的 glob 模式经过校验(不会意外展开)内置
来源与改动说明
- [ ]
glob设置--depth限制,防止对大型目录树造成 DoS内置来源与改动说明
临时文件
- [ ] 临时文件用内置
mktemp创建,而非可预测路径内置来源与改动说明
- [ ] 临时文件在
try/catch或等价结构中清理内置来源与改动说明
- [ ] 临时目录使用
mktemp --directory内置来源与改动说明
环境安全
- [ ]
$env.PATH不可被不可信输入修改内置来源与改动说明
- [ ] 运行不可信命令前清除危险环境变量(
LD_PRELOAD、DYLD_INSERT_LIBRARIES)内置来源与改动说明
- [ ] 在安全敏感场景中使用
with-env做限定作用域的环境变更内置来源与改动说明
---
2. 正确性
34 项类型安全
- [ ] 所有导出命令的参数都带类型注解内置
来源与改动说明
- [ ] I/O 管道签名(
]: type -> type {)与实际行为一致内置来源与改动说明
- [ ] 复杂类型使用正确语法:
record<name: string>、list<int>、table<col: type>内置来源与改动说明
- [ ] 可选参数使用
?后缀:name?: string内置来源与改动说明
- [ ] 无默认值的可选参数和带类型的命名选项按
oneof<T, nothing>处理;布尔开关标志保持bool内置来源与改动说明
- [ ] 剩余参数带类型:
...args: string内置来源与改动说明
- [ ] 运行时赋值注解在 Nu 0.114 默认的
enforce-runtime-annotations下合法内置来源与改动说明
错误处理
- [ ] 可能失败的操作都包裹在
try/catch中内置来源与改动说明
- [ ] 退出码重要时,用
complete检查外部命令内置来源与改动说明
- [ ] 测试不得在未规范化 ANSI、PTY 换行和
|边栏的情况下断言原始嵌套 Nu 诊断输出内置来源与改动说明
- [ ]
catch块包含有意义的错误上下文(不为空)内置来源与改动说明
- [ ]
finally用于清理副作用,而不是用作返回值内置来源与改动说明
- [ ]
catch块读取$err.details获取结构化诊断信息,而不是读取已移除的$err.json内置来源与改动说明
- [ ] 自定义错误包含带
span的label,以获得良好的错误消息内置来源与改动说明
- [ ] 元数据可用时,不得使用不带 span 的裸
error make {msg: '...'}内置来源与改动说明
空值安全
- [ ] 可选记录字段用
?访问:$rec.field?内置来源与改动说明
- [ ] 用
default提供兜底值:$val | default 'N/A'内置来源与改动说明
- [ ] 不得对外部/不可信来源的记录裸访问字段内置
来源与改动说明
- [ ]
$in被多次使用时尽早用let捕获内置来源与改动说明
逻辑正确性
- [ ]
for不用作最终表达式(返回 null,改用each)内置来源与改动说明
- [ ]
mut变量不在闭包中被捕获(会报错)内置来源与改动说明
- [ ]
source/use路径是const,而不是let内置来源与改动说明
- [ ] 对单个值的长
if/else if链优先改用match,除非if更清晰内置来源与改动说明
- [ ] 需要非 null 输出时,
if/match表达式有else/_兜底内置来源与改动说明
- [ ]
each不用于单个记录(改用items或transpose)内置来源与改动说明
- [ ] 打算对流输入逐行解析时,
parse先接lines内置来源与改动说明
- [ ] 运算符使用正确:非管道上下文中的
>是比较,不是重定向内置来源与改动说明
- [ ] 带命名标志的多行自定义命令调用写成单行或包裹在括号中内置
来源与改动说明
- [ ] SemVer 逻辑使用
into semver/into semver-range/semver bump,而不是手工拼改字符串内置来源与改动说明
外部命令
- [ ] 外部命令与内置命令同名时加
^前缀内置来源与改动说明
- [ ] 保持
find(Nushell 内置)与^find(Unix)的区分内置来源与改动说明
- [ ] 保持
sort(Nushell 内置)与^sort(Unix)的区分内置来源与改动说明
- [ ] 传给外部命令的参数分开传递(不拼接成字符串)内置
来源与改动说明
- [ ] 传给外部命令的格式字符串在简单转义场景用双引号,需要插值时用
char tab/char nl内置来源与改动说明
---
3. 风格与惯用法
32 项命名
- [ ] 命令:
kebab-case(fetch-user,而不是fetchUser或fetch_user)内置来源与改动说明
- [ ] 变量/参数:
snake_case($user_id,而不是$userId)内置来源与改动说明
- [ ] 环境变量:
SCREAMING_SNAKE_CASE($env.APP_VERSION)内置来源与改动说明
- [ ] 标志:
kebab-case(--output-dir,而不是--output_dir)内置来源与改动说明
- [ ] 优先使用完整单词(
$user_name,而不是$usr_nm)内置来源与改动说明
字符串格式优先级
- [ ] 数组中的裸词:
[foo bar]而不是["foo" "bar"]内置来源与改动说明
- [ ] 简单字符串用单引号:
'hello'而不是"hello"内置来源与改动说明
- [ ] 插值优先用单引号形式:
$'val: ($x)'而不是$"val: ($x)"内置来源与改动说明
- [ ] 需要字面
(的字符串用$"...\(...",绝不用$'...'—— 在内置来源与改动说明
$'...' 中圆括号总是开启一个表达式,\( 并不能将其转义
- [ ] 仅在需要转义序列时用双引号:
"\n"、"\t"内置来源与改动说明
- [ ] 正则表达式用原始字符串:
r#'pattern'#内置来源与改动说明
- [ ] 使用
str uppercase/str lowercase,而不是已弃用的str upcase/str downcase内置来源与改动说明
管道与函数式风格
- [ ] 优先用管道而非命令式循环内置
来源与改动说明
- [ ] 用
$items | get price | math sum而不是mut total; for ...内置来源与改动说明
- [ ] 用
ls | where size > 1mb而不是手工过滤内置来源与改动说明
- [ ] 用
enumerate而不是手工索引计数器内置来源与改动说明
- [ ] 用
reduce而不是mut累加器 +for内置来源与改动说明
- [ ] 对单个值的多分支分发优先用
match内置来源与改动说明
格式化
- [ ] 闭包中
|params|前不加空格:{|x| ...}而不是{ |x| ...}内置来源与改动说明
- [ ] 管道符两侧加空格:
cmd | cmd而不是cmd|cmd内置来源与改动说明
- [ ] 列表中省略逗号:
[1 2 3]而不是[1, 2, 3]内置来源与改动说明
- [ ] 记录中
:后加一个空格:{x: 1}而不是{x:1}内置来源与改动说明
- [ ] 超过 80 字符的表达式用多行格式内置
来源与改动说明
文档
- [ ] 导出命令在
def上方有#注释内置来源与改动说明
- [ ] 参数描述写成内联
#注释内置来源与改动说明
- [ ] 非平凡命令加
@example属性内置来源与改动说明
- [ ] 适用时用
@category做归类组织内置来源与改动说明
模块
- [ ] 只
export必要的定义内置来源与改动说明
- [ ] 命令与模块同名时使用
export def main内置来源与改动说明
- [ ] Nu 0.114+ 中调用方需要子模块命名空间时显式重导出子模块内置
来源与改动说明
- [ ] 私有辅助函数不导出内置
来源与改动说明
- [ ] 环境设置块使用
export-env内置来源与改动说明
---
4. 性能
13 项并行
- [ ] I/O 密集型工作(文件读取、HTTP 请求)使用
par-each内置来源与改动说明
- [ ] CPU 密集型工作(数据处理)使用
par-each内置来源与改动说明
- [ ] 并发控制重要时指定
--threads内置来源与改动说明
- [ ] 仅在顺序重要或列表极小时使用
each内置来源与改动说明
流式处理与内存
- [ ] 嵌套结果的流式处理用
each --flatten内置来源与改动说明
- [ ] 流式处理足够时不整体加载大文件内置
来源与改动说明
- [ ] 大文件逐行处理用
lines+ 管道内置来源与改动说明
- [ ] 用
peek检查流元数据/采样,而不是全量收集内置来源与改动说明
- [ ] 用
first N/take while尽早限制处理量内置来源与改动说明
缓存与计算
- [ ] 昂贵的结果缓存在
let绑定中,不重复计算内置来源与改动说明
- [ ]
glob加--depth,避免扫描巨型目录树内置来源与改动说明
- [ ] 小数据优先用内置命令而非外部命令内置
来源与改动说明
- [ ] 大规模操作使用外部工具(
^rg、^jq)内置来源与改动说明
---
5. 健壮性
14 项输入校验
- [ ] 参数标注类型(在解析期捕获误用)内置
来源与改动说明
- [ ] 关键参数在函数入口做范围/取值检查内置
来源与改动说明
- [ ] 面向用户的命令在处理前校验输入内置
来源与改动说明
- [ ] 返回类型一致(不要意外混用 null 与值)内置
来源与改动说明
文件操作
- [ ] 文件可能不存在时,
open前先检查path exists内置来源与改动说明
- [ ] 有意识地使用
save --force(会不加警告地覆盖)内置来源与改动说明
- [ ] 恰当处理文件编码(二进制用
open --raw)内置来源与改动说明
- [ ]
from xlsx/from ods的输出按由各工作表表格组成的记录处理内置来源与改动说明
- [ ] 电子表格导入使用
--noheaders、--first-row或--prefer-integers,而不是已移除的--header-row内置来源与改动说明
- [ ]
mkdir -v/mv -v/rm -v的输出按表格处理,而不是按解析文本内置来源与改动说明
- [ ] 传入多个路径时考虑
rm/mkdir的部分成功行为内置来源与改动说明
进程管理
- [ ] 长时间运行的外部进程有超时或取消机制内置
来源与改动说明
- [ ] 后台作业(
job spawn)被跟踪并清理内置来源与改动说明
- [ ] 关键外部命令检查退出码内置
来源与改动说明
---
评审流程
0 项1. 通读整个脚本 —— 理解目的、入口点、数据流 2. 安全轮查 —— 系统检查第 1 节各项 3. 正确性轮查 —— 验证类型、错误处理、空值安全 4. 风格轮查 —— 命名、字符串、格式化、文档 5. 性能轮查 —— 并行、流式处理、缓存机会 6. 健壮性轮查 —— 输入校验、文件安全、进程管理 7. 汇总发现 —— 按严重程度分组,优先突出安全问题