feat: custom NIX_PATH and Flake registry

docs/.vitepress/config.ts

@@ -159,6 +159,10 @@ function themeConfigEnglish() {
               text: "Simplify NixOS-related Commands",
               link: "/best-practices/simplify-nixos-related-commands.md",
             },
+            {
+              text: "Custom NIX_PATH and Flake Registry",
+              link: "/best-practices/nix-path-and-flake-registry.md",
+            },
             {
               text: "Remote Deployment",
               link: "/best-practices/remote-deployment.md",
@@ -341,6 +345,10 @@ function themeConfigChinese() {
               text: "使用 Makefile 简化常用命令",
               link: "/zh/best-practices/simplify-nixos-related-commands.md",
             },
+            {
+              text: "自定义 NIX_PATH 与 Flake Registry",
+              link: "/zh/best-practices/nix-path-and-flake-registry.md",
+            },
             {
               text: "远程部署 Nix 配置",
               link: "/zh/best-practices/remote-deployment.md",

docs/best-practices/nix-path-and-flake-registry.md

@@ -0,0 +1,41 @@
+# Custom NIX_PATH and Flake Registry {#custom-nix-path-and-flake-registry}
+
+## Introduction to NIX_PATH {#nix-path-introduction}
+
+The Nix search path is controlled by the environment variable `NIX_PATH`, which follows the same format as the Linux `PATH` environment variable, consisting of multiple paths separated by colons.
+
+Paths in Nix expressions that look like `<name>` are resolved using the path named `name` from the `NIX_PATH`.
+
+This usage pattern is no longer recommended under the Flakes feature because it results in Flake builds depending on a mutable environment variable `NIX_PATH`, compromising reproducibility.
+
+However, in certain scenarios, we still need to use `NIX_PATH`, such as when we frequently use the command `nix repl '<nixpkgs>'`, which utilizes the Nixpkgs found through `NIX_PATH` search.
+
+## Introduction to Flakes Registry {#flakes-registry-introduction}
+
+The Flakes Registry is a center for Flake registration that assists us in using shorter IDs instead of lengthy flake repository addresses when using commands like `nix run`, `nix shell`, and more.
+
+By default, Nix looks up the corresponding GitHub repository address for this ID from <https://github.com/NixOS/flake-registry/blob/master/flake-registry.json>.
+
+For instance, if we execute `nix run nixpkgs#ponysay hello`, Nix will automatically retrieve the GitHub repository address for `nixpkgs` from the aforementioned JSON file. It then downloads the repository, locates the `flake.nix` within, and runs the corresponding `ponysay` package.
+
+## Custom NIX_PATH and Flake Registry {#custom-nix-path-and-flake-registry}
+
+The roles of `NIX_PATH` and the Flake Registry have been explained earlier.
+In daily use, we typically want the `nixpkgs` used in commands like `nix repl '<nixpkgs>'`, `nix run nixpkgs#ponysay hello` to match the system's `nixpkgs`. This requires us to customize the `NIX_PATH` and Flake Registry.
+
+In your NixOS configuration, adding the following module will achieve the mentioned requirements:
+
+```nix
+{
+  # Make `nix run nixpkgs#nixpkgs` use the same nixpkgs as the one used by this flake.
+  nix.registry.nixpkgs.flake = nixpkgs;
+
+  # Make `nix repl '<nixpkgs>'` use the same nixpkgs as the one used by this flake.
+  environment.etc."nix/inputs/nixpkgs".source = "${nixpkgs}";
+  nix.nixPath = ["/etc/nix/inputs"];
+}
+```
+
+## References
+
+- [Chapter 15. Nix Search Paths - Nix Pills](https://nixos.org/guides/nix-pills/nix-search-paths.html)

docs/zh/best-practices/nix-path-and-flake-registry.md

@@ -0,0 +1,43 @@
+# 自定义 NIX_PATH 与 Flake Registry {#custom-nix-path-and-flake-registry}
+
+## NIX_PATH 介绍 {#nix-path-introduction}
+
+Nix 搜索路径由环境变量 `NIX_PATH` 控制，它的格式与 Linux 的 `PATH` 环境变量一致，由冒号分隔的多个路径组成。
+
+Nix 表达式中形如 `<name>` 的路径会被解析为 `NIX_PATH` 中名为 `name` 的路径。
+
+这种使用方式在 Flakes 特性下已经不推荐使用了，因为它会导致 Flake 的构建结果依赖一个可变的环境变量 `NIX_PATH`，可复现能力大打折扣。
+
+但是在某些场景下，我们还是需要使用 `NIX_PATH`，比如我们前面多次使用了 `nix repl '<nixpkgs>'` 命令，它就是使用了从 `NIX_PATH` 搜索到的 Nixpkgs。
+
+## Flakes Registry 介绍 {#flakes-registry-introduction}
+
+Flake Registry 是一个 Flake 注册中心，它可以帮助我们在使用 `nix run`, `nix shell` 等命令时，使用一个简短的 id 来代替长长的 flake 仓库地址。
+
+默认情况下，Nix 会从 <https://github.com/NixOS/flake-registry/blob/master/flake-registry.json> 中找到这个 id 对应的 github 仓库地址。
+
+比如说我们执行 `nix run nixpkgs#ponysay hello`，nix 会自动从上述 json 文件中找到 `nixpkgs` 对应的 github 仓库地址，然后下载这个仓库，再通过其中的 `flake.nix` 查找对应的 `ponysay` 包并运行它。
+
+
+## 自定义 NIX_PATH 与 Flake Registry {#custom-nix-path-and-flake-registry}
+
+前面说明了 `NIX_PATH` 与 Flake Registry 的作用。
+在日常使用中，我们一般都会希望能在执行 `nix repl '<nixpkgs>'`, `nix run nixpkgs#ponysay hello` 等命令时，使用的 nixpkgs 与系统一致，这就需要我们自定义 `NIX_PATH` 与 Flake Registry。
+
+在你的 NixOS 配置中，添加如下 module 即可实现上述需求：
+
+```nix
+{
+  # make `nix run nixpkgs#nixpkgs` use the same nixpkgs as the one used by this flake.
+  nix.registry.nixpkgs.flake = nixpkgs;
+
+  # make `nix repl '<nixpkgs>'` use the same nixpkgs as the one used by this flake.
+  environment.etc."nix/inputs/nixpkgs".source = "${nixpkgs}";
+  nix.nixPath = ["/etc/nix/inputs"];
+}
+```
+
+## 参考
+
+- [Chapter 15. Nix Search Paths - Nix Pills](https://nixos.org/guides/nix-pills/nix-search-paths.html)
+