用 Rust 开发前端基建工具

Rust 在最近几年在前端基建这一块有很大的发展。比如用于 lint 的 oxlint， 用于构建的 rspack 等等。这些工具都是用 Rust 写的，然后通过 Node.js 的 binding 连接到前端项目中。

很多前端小伙伴看这些项目的源码的时候也会一头雾水，不知道怎么编译，怎么运行。这里我就以 rolldown 为例简单介绍一下如何用 Rust 开发前端基建工具。

​

我这里将 rust 写的工具分为两个大部分。

1. rust 实现的部分，以及如何编译成 node binding。
2. js 中如何使用前面编译好的 node binding。

这两个环节打通了，那一个 rust 写的工具就可以在前端项目中使用了。

什么是 node binding

node binding 是一个用于连接 Node.js 与其他语言的工具。比如你可以用 cpp 编写一个模块，然后通过 node binding 将这个模块连接到 Node.js 中。

有了 node binding，你就可以在 Node.js 中使用其他语言编写的模块了，只要你能够将你的语言写的包编译成符合规范的 node binding 就好了。

什么是 rolldown

rolldown 是一个用 Rust 编写的前端基建工具，它可以将 JavaScript 代码转换为 AST，然后通过 AST 进行一系列的操作，比如优化、压缩等等。不同 rspack api 对标的是 webpack，rolldown 开发的时候 api 对标的是 Rollup API。

rolldown 的作者是尤雨溪，rolldown 会被 Vite 2.0 用作默认的构建工具。

node binding 的编译

rolldown 通过 napi 与 Node.js 进行交互。

通过 rolldown 源码可以发现，它在 package.json 中定义了如下 napi 的配置：

"napi": {
    "binaryName": "rolldown-binding",
    "packageName": "@rolldown/binding",
    "targets": [
      "x86_64-apple-darwin",
      "x86_64-pc-windows-msvc",
      "x86_64-unknown-linux-gnu",
      "x86_64-unknown-linux-musl",
      "i686-pc-windows-msvc",
      "armv7-unknown-linux-gnueabihf",
      "aarch64-unknown-linux-gnu",
      "aarch64-apple-darwin",
      "aarch64-unknown-linux-musl",
      "aarch64-pc-windows-msvc"
    ]
  },

有了这个配置，就可以通过 napi build 命令来编译 napi 模块。

{
    "scripts": {
        "build-binding": "napi build -o=./src --manifest-path ../../crates/rolldown_binding/Cargo.toml --platform -p rolldown_binding --js binding.js --dts binding.d.ts --dts-header \"type MaybePromise<T> = T | Promise<T>\ntype Nullable<T> = T | null | undefined\ntype VoidNullable<T = void> = T | null | undefined | void\"",

    "build-binding:release": "napi build -o=./src --release --manifest-path ../../crates/rolldown_binding/Cargo.toml --platform -p rolldown_binding --js binding.js --dts binding.d.ts --dts-header \"type MaybePromise<T> = T | Promise<T>\ntype Nullable<T> = T | null | undefined\ntype VoidNullable<T = void> = T | null | undefined | void\"",
    }
}

这样执行 npm run build-binding 就可以编译出 binding.js 和 binding.d.ts 文件了。后面我们会看到这两个文件是如何使用的。

大家可能对 node-saa 比较眼熟，资深的前端或多或少都遇到过 node-saas 安装报错，因此对它还是比较眼熟的。rolldown 与 node-saa 类似。node-saas 底层是 cpp 实现的，通过 node-gyp 来编译的，而 rolldown 底层是 rust 写的，通过 napi 来编译的。

node-saas 的工作原理大概是：

1. node-gyp 首先读取用于描述插件的 binding.gyp 文件，这个文件是用 Python 的 GYP（Generate Your Projects）语言编写的。

2. 然后，node-gyp 会生成对应平台和编译器的项目构建文件。例如，在 Windows 上，它会生成 .vcxproj 文件，这个文件可以被 MSBuild 使用；在 Unix 系统上，它会生成 Makefile 文件。

3. 最后，node-gyp 调用相应的构建工具（如 make 或 msbuild）来编译源代码，生成 Node.js 可以加载的二进制插件。

需要注意的是，node-gyp 需要 Python 和 C++ 编译器的支持，因此在使用之前需要确保这些依赖已经正确安装在系统上。

如果你对 node-gyp 也不太了解，可以看下死月的 《Node.js：来一打 C++ 扩展》，这里附上这本书的配套源码，方便大家学习，地址：https://github.com/XadillaX/nyaa-nodejs-demo

node binding 的使用

前面讲了 rolldown 的编译过程，接下来我们来看看编译好的 node binding 是怎么样的，以及如何使用。

rolldown 的核心 rust 代码在这里实现：https://github.com/rolldown/rolldown/blob/main/crates/rolldown_binding/src/bundler.rs

可以看出这里也是通过 napi 来实现的。

前面讲到：执行 npm run build-binding 就可以编译出 binding.js 和 binding.d.ts 文件了。

那么 binding.js 是什么样？以及如何使用呢？

回答这两个问题前，我们来看下 rolldown 是如何使用这两个文件的。

import { Bundler } from '../binding'
// ...

export async function createBundler(
  inputOptions: InputOptions,
  outputOptions: OutputOptions,
): Promise<Bundler> {
  // ...
  return new Bundler(bindingInputOptions, normalizeOutputOptions(outputOptions))
}

代码截取自 https://github.com/rolldown/rolldown/blob/main/packages/rolldown/src/utils/create-bundler.ts

可以看出 binding.js 是一个模块，它对外暴露了 rust 实现的 Bundler 类，使得 JS 代码可以直接调用 rust 实现的 Bundler 类。

那我们进一步来看看 binding.js 是什么样的。

// prettier-ignore
/* eslint-disable */
/* auto-generated by NAPI-RS */

const { readFileSync } = require('fs')

let nativeBinding = null
const loadErrors = []

const isMusl = () => {
  let musl = false
  if (process.platform === 'linux') {
    musl = isMuslFromFilesystem()
    if (musl === null) {
      musl = isMuslFromReport()
    }
    if (musl === null) {
      musl = isMuslFromChildProcess()
    }
  }
  return musl
}

const isFileMusl = (f) => f.includes('libc.musl-') || f.includes('ld-musl-')

const isMuslFromFilesystem = () => {
  try {
    return readFileSync('/usr/bin/ldd', 'utf-8').includes('musl')
  } catch {
    return null
  }
}

const isMuslFromReport = () => {
  const report =
    typeof process.report.getReport === 'function'
      ? process.report.getReport()
      : null
  if (!report) {
    return null
  }
  if (report.header && report.header.glibcVersionRuntime) {
    return false
  }
  if (Array.isArray(report.sharedObjects)) {
    if (report.sharedObjects.some(isFileMusl)) {
      return true
    }
  }
  return false
}

const isMuslFromChildProcess = () => {
  try {
    return require('child_process')
      .execSync('ldd --version', { encoding: 'utf8' })
      .includes('musl')
  } catch (e) {
    // If we reach this case, we don't know if the system is musl or not, so is better to just fallback to false
    return false
  }
}

function requireNative() {
  if (process.platform === 'android') {
    if (process.arch === 'arm64') {
      try {
        return require('./rolldown-binding.android-arm64.node')
      } catch (e) {
        loadErrors.push(e)
      }
      try {
        return require('@rolldown/binding-android-arm64')
      } catch (e) {
        loadErrors.push(e)
      }
    } else if (process.arch === 'arm') {
      try {
        return require('./rolldown-binding.android-arm-eabi.node')
      } catch (e) {
        loadErrors.push(e)
      }
      try {
        return require('@rolldown/binding-android-arm-eabi')
      } catch (e) {
        loadErrors.push(e)
      }
    } else {
      loadErrors.push(
        new Error(`Unsupported architecture on Android ${process.arch}`),
      )
    }
  } else if (process.platform === 'win32') {
    if (process.arch === 'x64') {
      try {
        return require('./rolldown-binding.win32-x64-msvc.node')
      } catch (e) {
        loadErrors.push(e)
      }
      try {
        return require('@rolldown/binding-win32-x64-msvc')
      } catch (e) {
        loadErrors.push(e)
      }
    } else if (process.arch === 'ia32') {
      try {
        return require('./rolldown-binding.win32-ia32-msvc.node')
      } catch (e) {
        loadErrors.push(e)
      }
      try {
        return require('@rolldown/binding-win32-ia32-msvc')
      } catch (e) {
        loadErrors.push(e)
      }
    } else if (process.arch === 'arm64') {
      try {
        return require('./rolldown-binding.win32-arm64-msvc.node')
      } catch (e) {
        loadErrors.push(e)
      }
      try {
        return require('@rolldown/binding-win32-arm64-msvc')
      } catch (e) {
        loadErrors.push(e)
      }
    } else {
      loadErrors.push(
        new Error(`Unsupported architecture on Windows: ${process.arch}`),
      )
    }
  } else if (process.platform === 'darwin') {
    try {
      return require('./rolldown-binding.darwin-universal.node')
    } catch (e) {
      loadErrors.push(e)
    }
    try {
      return require('@rolldown/binding-darwin-universal')
    } catch (e) {
      loadErrors.push(e)
    }

    if (process.arch === 'x64') {
      try {
        return require('./rolldown-binding.darwin-x64.node')
      } catch (e) {
        loadErrors.push(e)
      }
      try {
        return require('@rolldown/binding-darwin-x64')
      } catch (e) {
        loadErrors.push(e)
      }
    } else if (process.arch === 'arm64') {
      try {
        return require('./rolldown-binding.darwin-arm64.node')
      } catch (e) {
        loadErrors.push(e)
      }
      try {
        return require('@rolldown/binding-darwin-arm64')
      } catch (e) {
        loadErrors.push(e)
      }
    } else {
      loadErrors.push(
        new Error(`Unsupported architecture on macOS: ${process.arch}`),
      )
    }
  } else if (process.platform === 'freebsd') {
    if (process.arch === 'x64') {
      try {
        return require('./rolldown-binding.freebsd-x64.node')
      } catch (e) {
        loadErrors.push(e)
      }
      try {
        return require('@rolldown/binding-freebsd-x64')
      } catch (e) {
        loadErrors.push(e)
      }
    } else if (process.arch === 'arm64') {
      try {
        return require('./rolldown-binding.freebsd-arm64.node')
      } catch (e) {
        loadErrors.push(e)
      }
      try {
        return require('@rolldown/binding-freebsd-arm64')
      } catch (e) {
        loadErrors.push(e)
      }
    } else {
      loadErrors.push(
        new Error(`Unsupported architecture on FreeBSD: ${process.arch}`),
      )
    }
  } else if (process.platform === 'linux') {
    if (process.arch === 'x64') {
      if (isMusl()) {
        try {
          return require('./rolldown-binding.linux-x64-musl.node')
        } catch (e) {
          loadErrors.push(e)
        }
        try {
          return require('@rolldown/binding-linux-x64-musl')
        } catch (e) {
          loadErrors.push(e)
        }
      } else {
        try {
          return require('./rolldown-binding.linux-x64-gnu.node')
        } catch (e) {
          loadErrors.push(e)
        }
        try {
          return require('@rolldown/binding-linux-x64-gnu')
        } catch (e) {
          loadErrors.push(e)
        }
      }
    } else if (process.arch === 'arm64') {
      if (isMusl()) {
        try {
          return require('./rolldown-binding.linux-arm64-musl.node')
        } catch (e) {
          loadErrors.push(e)
        }
        try {
          return require('@rolldown/binding-linux-arm64-musl')
        } catch (e) {
          loadErrors.push(e)
        }
      } else {
        try {
          return require('./rolldown-binding.linux-arm64-gnu.node')
        } catch (e) {
          loadErrors.push(e)
        }
        try {
          return require('@rolldown/binding-linux-arm64-gnu')
        } catch (e) {
          loadErrors.push(e)
        }
      }
    } else if (process.arch === 'arm') {
      try {
        return require('./rolldown-binding.linux-arm-gnueabihf.node')
      } catch (e) {
        loadErrors.push(e)
      }
      try {
        return require('@rolldown/binding-linux-arm-gnueabihf')
      } catch (e) {
        loadErrors.push(e)
      }
    } else if (process.arch === 'riscv64') {
      if (isMusl()) {
        try {
          return require('./rolldown-binding.linux-riscv64-musl.node')
        } catch (e) {
          loadErrors.push(e)
        }
        try {
          return require('@rolldown/binding-linux-riscv64-musl')
        } catch (e) {
          loadErrors.push(e)
        }
      } else {
        try {
          return require('./rolldown-binding.linux-riscv64-gnu.node')
        } catch (e) {
          loadErrors.push(e)
        }
        try {
          return require('@rolldown/binding-linux-riscv64-gnu')
        } catch (e) {
          loadErrors.push(e)
        }
      }
    } else if (process.arch === 's390x') {
      try {
        return require('./rolldown-binding.linux-s390x-gnu.node')
      } catch (e) {
        loadErrors.push(e)
      }
      try {
        return require('@rolldown/binding-linux-s390x-gnu')
      } catch (e) {
        loadErrors.push(e)
      }
    } else {
      loadErrors.push(
        new Error(`Unsupported architecture on Linux: ${process.arch}`),
      )
    }
  } else {
    loadErrors.push(
      new Error(
        `Unsupported OS: ${process.platform}, architecture: ${process.arch}`,
      ),
    )
  }
}

nativeBinding = requireNative()

if (!nativeBinding || process.env.NAPI_RS_FORCE_WASI) {
  try {
    nativeBinding = require('./rolldown-binding.wasi.cjs')
  } catch (err) {
    if (process.env.NAPI_RS_FORCE_WASI) {
      console.error(err)
    }
  }
  if (!nativeBinding) {
    try {
      nativeBinding = require('@rolldown/binding-wasm32-wasi')
    } catch (err) {
      if (process.env.NAPI_RS_FORCE_WASI) {
        console.error(err)
      }
    }
  }
}

if (!nativeBinding) {
  if (loadErrors.length > 0) {
    // TODO Link to documentation with potential fixes
    //  - The package owner could build/publish bindings for this arch
    //  - The user may need to bundle the correct files
    //  - The user may need to re-install node_modules to get new packages
    throw new Error('Failed to load native binding', { cause: loadErrors })
  }
  throw new Error(`Failed to load native binding`)
}

module.exports.BindingPluginContext = nativeBinding.BindingPluginContext
module.exports.Bundler = nativeBinding.Bundler

这里有几个关键信息:

1. 这个文件是 NAPI-RS 自动生成的，即前面说的 napi 构建的结果。
2. 这个文件会根据不同的平台和架构加载不同的 binding 文件。这是因为不同平台和架构的二进制文件是不同的。了解汇编的同学都知道。
3. 会尝试加载本地的 .node 文件，如果没有找到，会尝试加载对应发布在 npm 上 @rolldown 命名空间下的包。

关于发布 npm 包，我的猜测是 napi 自动发布的。

总结

目前 rust 来写前端基建工具已经是一个比较成熟的方案了。比如 unplugin-parcel-macros 也是用 rust 实现的的构建插件，同样是基于 napi 构建，支持 webpack ，vite， rollup 等。功能是将一些构建的时候运行代码，然后将运行结果插入到代码中，从而节省运行时的性能。

通过这篇文章，我们了解了 rolldown 是如何用 Rust 编写的前端基建工具，以及如何通过 napi 构建 node binding，以及如何在 JS 中使用 node binding。

具体来说，如果你想用 rust 开发前端基建工具，一般可以采用如下的步骤：

1. 用 rust 实现你的工具。
2. 通过 napi 构建 node binding。
3. 在 JS 中使用 node binding。

对于其他语言，比如 cpp 基本流程是一样的，只是构建 node binding 的工具不同。

比如使用 cpp 开发前端基建工具，步骤可能是：

1. 用 cpp 实现你的工具。
2. 通过 node-gyp 构建 node binding。
3. 在 JS 中使用 node binding。

你也可以直接使用一些基于 napi-rs 的工具，这样就可以节省一些时间，比如 neon-rs 。

如下脚本就可以快速创建一个脚手架项目。

npm init neon cpu-count
cd cpu-count
npm install

修改代码，写一些 rust 代码实现功能，然后执行 npm run build 就可以构建 node binding 了。

cargo clean
npm run build -- --release
node
> const cpuCount = require('.')
> cpuCount.get()
4