`lib.mkOption` 完整总结#

一、核心作用#

lib.mkOption 是 Nix 模块系统中定义配置选项的基础函数，用于创建可配置、可组合、类型安全的配置接口。

本质：将”定义可配置内容”与”设置具体值”分离，实现声明式配置。

二、基本用法#

语法结构#

1
options.选项名 = lib.mkOption {
2
  type = lib.types.<类型>;      # 数据类型（推荐）
3
  default = <默认值>;           # 默认值（可选）
4
  description = "说明文字";     # 文档描述（推荐）
5
  example = <示例>;             # 使用示例（可选）
6
  apply = <转换函数>;           # 值处理函数（可选）
7
};

常用类型#

1
# 基础类型
2
lib.types.bool          # 布尔值
3
lib.types.int           # 整数
4
lib.types.str           # 字符串
5
lib.types.path          # 路径
6

7
# 容器类型
8
lib.types.listOf <类型>         # 列表
9
lib.types.attrsOf <类型>        # 属性集
10
lib.types.nullOr <类型>         # 可空类型
11
lib.types.enum [值1, 值2]       # 枚举
12

13
# 复合类型
14
lib.types.submodule { ... }     # 嵌套子模块

实际例子#

1
{ lib, config, ... }:
2
{
3
  # 定义选项
4
  options.myService = {
5
    enable = lib.mkOption {
6
      type = lib.types.bool;
7
      default = false;
8
      description = "是否启用服务";
9
    };
10

11
    port = lib.mkOption {
12
      type = lib.types.int;
13
      default = 8080;
14
      description = "服务端口";
15
    };
16
  };
17

18
  # 使用选项值
19
  config = lib.mkIf config.myService.enable {
20
    systemd.services.myService = {
21
      serviceConfig.ExecStart =
22
        "${pkgs.myapp}/bin/myapp --port ${toString config.myService.port}";
23
    };
24
  };
25
}

三、优势对比#

对比表格#

维度	硬编码	lib.mkOption
可修改性	❌ 值写死，难以修改	✅ 可在任何模块中覆盖
类型安全	❌ 无类型检查	✅ 构建时类型验证
可复用性	❌ 重复代码多	✅ 一处定义，到处引用
文档化	❌ 需手动维护文档	✅ 自动生成文档
模块化	❌ 紧耦合	✅ 松耦合，易组合
条件配置	🟡 需要大量 if-else	✅ 使用 `lib.mkIf` 优雅处理
动态选择	❌ 困难	✅ 通过 `config.xxx` 轻松实现

代码对比#

❌ 硬编码方式#

1
{
2
  # 需要在每个地方重复
3
  programs.git.userEmail = "zno233@outlook.com";
4
  services.email.account = "zno233@outlook.com";
5
  home.file.".signature".text = "zno233@outlook.com";
6

7
  # 无法跨文件修改
8
  # 无类型检查
9
  # 无自动文档
10
}

✅ mkOption 方式#

1
# 定义模块
2
{
3
  options.userEmail = lib.mkOption {
4
    type = lib.types.str;
5
    default = "zno233@outlook.com";
6
    description = "用户邮箱地址";
7
  };
8
}
9

10
# 使用模块
11
{
12
  programs.git.userEmail = config.userEmail;
13
  services.email.account = config.userEmail;
14
  home.file.".signature".text = config.userEmail;
15
}
16

17
# 可以在任何地方覆盖
18
{ userEmail = "alice@example.com"; }

四、核心优势详解#

1. 声明式接口#

定义”可以配置什么”而不是”值是什么”
提供清晰的配置契约

2. 跨模块配置#

1
# module-a.nix 定义
2
options.feature.enable = lib.mkOption { ... };
3

4
# module-b.nix 使用
5
config = lib.mkIf config.feature.enable { ... };

3. 动态选择能力#

1
{
2
  options.profile = lib.mkOption {
3
    type = lib.types.enum [ "work" "personal" ];
4
    default = "personal";
5
  };
6

7
  config.programs.git.userEmail =
8
    if config.profile == "work"
9
    then "work@company.com"
10
    else "personal@example.com";
11
}

4. 类型安全保障#

1
options.port = lib.mkOption {
2
  type = lib.types.int;
3
  default = 8080;
4
};
5

6
# ❌ 错误会在构建时被发现
7
config.port = "8080";  # 类型错误！

五、最佳实践#

1
{ lib, config, ... }:
2
{
3
  options.myApp = {
4
    # 1. 总是指定类型
5
    enable = lib.mkOption {
6
      type = lib.types.bool;
7
      default = false;
8
      description = "启用应用";
9
    };
10

11
    # 2. 提供合理的默认值
12
    dataDir = lib.mkOption {
13
      type = lib.types.path;
14
      default = "/var/lib/myapp";
15
      description = "数据目录";
16
    };
17

18
    # 3. 添加清晰的描述
19
    port = lib.mkOption {
20
      type = lib.types.int;
21
      default = 3000;
22
      description = "HTTP 监听端口";
23
      example = 8080;
24
    };
25

26
    # 4. 使用 apply 进行值验证
27
    maxConnections = lib.mkOption {
28
      type = lib.types.int;
29
      default = 100;
30
      apply = n:
31
        if n < 1 then throw "连接数必须大于 0" else n;
32
    };
33
  };
34
}

六、关键理念#

lib.mkOption 的本质是提供一个可配置的抽象层，使配置既灵活又安全。它不是”无法动态选择”，而是让动态配置变得更优雅、更可维护。

一句话总结：lib.mkOption 将配置从”硬编码的值”变成”可定制的接口”，这是 NixOS 模块系统实现强大组合能力的基石。

音乐

音乐

`lib.mkOption` 完整总结#

一、核心作用#

二、基本用法#

语法结构#

常用类型#

实际例子#

三、优势对比#

对比表格#

代码对比#

❌ 硬编码方式#

✅ mkOption 方式#

四、核心优势详解#

1. 声明式接口#

2. 跨模块配置#

3. 动态选择能力#

4. 类型安全保障#

五、最佳实践#

六、关键理念#

文章分享

音乐

文章目录

音乐

音乐

lib.mkOption 总结

lib.mkOption 完整总结#

一、核心作用#

二、基本用法#

语法结构#

常用类型#

实际例子#

三、优势对比#

对比表格#

代码对比#

❌ 硬编码方式#

✅ mkOption 方式#

四、核心优势详解#

1. 声明式接口#

2. 跨模块配置#

3. 动态选择能力#

4. 类型安全保障#

五、最佳实践#

六、关键理念#

文章分享

音乐

文章目录

`lib.mkOption` 完整总结#