麒麟startup.nsh脚本执行失败原因？

Question

麒麟系统中startup.nsh脚本执行失败的常见原因之一是脚本文件编码格式不正确。startup.nsh需保存为UTF-8无BOM格式，若使用Windows默认的ANSI或带BOM的UTF-8编码，可能导致UEFI Shell解析失败，报“Invalid command”或直接跳过执行。此外，脚本首行命令格式错误、使用了不支持的Shell命令或路径中含有中文及特殊字符，也会引发执行中断。建议统一使用纯英文路径与标准UEFI Shell指令，并通过Hex编辑器确认文件编码合规。

Answer 1

1. 背景与问题引入

在基于国产化平台的系统部署中，麒麟操作系统因其高安全性与自主可控特性被广泛应用于政府、金融及关键基础设施领域。其中，在UEFI固件环境中通过startup.nsh脚本实现自动化启动流程是一种常见做法。然而，大量现场反馈表明：该脚本执行失败的问题频繁发生，而其根源往往并非逻辑错误，而是由看似微小但影响深远的技术细节所致。

最典型的案例之一是文件编码格式不规范。许多开发人员习惯于使用Windows记事本或非专业编辑器编写脚本，导致生成的startup.nsh文件默认采用ANSI或UTF-8 with BOM编码，从而触发UEFI Shell解析异常。

2. 编码格式的影响机制分析

• UTF-8无BOM：标准UEFI Shell仅支持此编码格式，确保字节流可被正确识别为ASCII兼容文本。
• UTF-8 with BOM：前三个字节EF BB BF会被Shell误读为非法命令前缀，导致首行报“Invalid command”。
• ANSI/GBK：非Unicode编码可能导致中文字符乱码，甚至中断整个脚本解析过程。

以下为不同编码下Hexdump输出对比：

编码类型	十六进制头部（前4字节）	是否兼容UEFI
UTF-8 无BOM	23 2F 73 68	✅ 是
UTF-8 带BOM	EF BB BF 23	❌ 否
ANSI (GBK)	23 2F 73 68	⚠️ 视内容而定
UTF-16 LE	FF FE 23 00	❌ 绝对不支持

3. 深层技术原理剖析

UEFI Shell遵循UEFI Specification 2.10中的脚本解析规则，其内部使用简单的逐行扫描机制，并依赖C-style字符串处理函数进行指令分词。当遇到BOM标记时，由于该标记不属于任何有效命令语法树节点，解析器直接判定为语法错误并跳过后续执行。

此外，Shell环境变量和路径解析模块不具备多字节编码检测能力，若路径包含中文如/设备/启动/nsh，将导致LoadImage()调用失败。

4. 典型故障排查流程图

```mermaid
graph TD
    A[startup.nsh执行失败] --> B{是否报Invalid command?}
    B -- 是 --> C[检查首行是否存在BOM]
    B -- 否 --> D[检查路径是否含中文或特殊字符]
    C --> E[使用Hex编辑器查看前3字节]
    E -- EF BB BF --> F[重新保存为UTF-8无BOM]
    E -- 无BOM --> G[验证首行命令合法性]
    D --> H[修改路径为纯英文]
    F --> I[重新烧录测试]
    G --> I
    H --> I
    I --> J[问题解决?]
    J -- 否 --> K[启用UEFI日志调试模式]
    J -- 是 --> L[闭环]
```

5. 实践解决方案与最佳实践

1. 使用支持编码选择的专业编辑器（如Notepad++、VS Code）创建startup.nsh；
2. 保存时明确选择“UTF-8 without BOM”选项；
3. 避免使用中文路径或空格，推荐格式：\EFI\BOOT\startup.nsh；
4. 首行应为合法UEFI命令，例如：fs0: 或 echo -on；
5. 禁用所有扩展命令（如grep、find），仅使用UEFI Shell内置指令集；
6. 通过hexdump -C startup.nsh | head -n 1确认无BOM存在；
7. 在QEMU/OVMF环境中预先仿真验证脚本行为；
8. 建立CI/CD流水线自动校验脚本编码合规性；
9. 部署前使用脚本签名机制防止意外篡改；
10. 记录UEFI Shell输出日志用于回溯分析。

6. 高级调试技巧与工具链推荐

对于复杂场景，建议结合如下工具进行深度诊断：

# 使用xxd查看二进制内容
xxd startup.nsh | head -n 2

# 在OVMF环境下启用Shell日志
setup_var 0x1234 0x1  # 开启Debug Output

# 检查当前FS映射状态
map -r

同时可集成Python脚本自动化检测编码：

import chardet

with open('startup.nsh', 'rb') as f:
    raw = f.read(4)
    encoding = chardet.detect(raw)['encoding']
    has_bom = raw.startswith(b'\xef\xbb\xbf')

print(f"Detected: {encoding}, Has BOM: {has_bom}")
if has_bom:
    print("❌ Error: UTF-8 with BOM detected. Please convert.")