> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/di-40-zhang-kai-fa-huan-jing/di-40.7-jie-node-js-kai-fa-huan-jing.md).

# 40.7 Node.js 开发环境

Node.js 依赖特定版本的 **/lib/libcrypto.so**，在 FreeBSD 上安装前需先更新基本系统。

## 更新基本系统

使用 pkg 安装的二进制 Node.js 依赖特定版本的 **/lib/libcrypto.so.xxx** 文件，在 FreeBSD 上使用 Node.js 时，需要关注 FreeBSD 系统的版本，尤其是当 pkg 配置为使用 latest 源时。

在 FreeBSD 上安装 Node.js 前，应先更新基本系统。

安装 npm 或 yarn 时，将自动安装对应版本的 Node.js；Bun 则使用自身运行时，不依赖 Node.js。

## Node.js 包管理器比较

| 评估维度          | npm                            | Yarn                             | Bun                       |
| ------------- | ------------------------------ | -------------------------------- | ------------------------- |
| 底层开发语言        | JavaScript                     | JavaScript                       | Zig                       |
| 执行运行时         | Node.js                        | Node.js                          | 原生 Bun Runtime            |
| 依赖解析机制        | 扁平化依赖树 + hoisting              | node\_modules / Plug'n'Play（PnP） | 高并发安装 + 扁平化 node\_modules |
| 磁盘存储策略        | 物理 `node_modules`              | `node_modules` 或 PnP 虚拟解析        | 全局缓存 + 硬链接/克隆优化           |
| 锁定文件          | `package-lock.json`            | `yarn.lock`                      | `bun.lock`                |
| TypeScript 支持 | 依赖 `tsc` / `tsx` / `esbuild` 等 | 同 npm                            | 原生执行 `.ts`                |
| 兼容性           | Node.js 官方标准                   | 高兼容性                             | Node API 兼容有待完善           |

其中，Bun 是一个 JavaScript 运行时，而不仅仅是 Node.js 包管理器。

## Bun

使用 pkg 安装：

```sh
pkg install bun
```

或使用 Ports 安装：

```sh
# cd /usr/ports/lang/bun/
# make install clean
```

## Yarn

使用 pkg 安装：

```sh
# pkg install yarn
```

或使用 Ports 安装：

```sh
# cd /usr/ports/www/yarn/
# make install clean
```

## NPM

使用 pkg 安装：

```sh
# pkg install npm
```

或使用 Ports 安装：

```sh
# cd /usr/ports/www/npm/
# make install clean
```

### FreeBSD NPM 切换软件源

设置 npm 使用国内镜像源以加快下载速度：

```sh
# npm config set registry https://registry.npmmirror.com
```

该站点为原淘宝镜像站，详情请见 <https://npmmirror.com>，提供 NPM 国内镜像加速服务。

## 故障排除与未竟事宜

### ld-elf.so.1 错误

如果跳过 FreeBSD 基本系统的更新而直接安装软件，则可能遇到以下错误：

```sh
$ node              # 启动 Node.js 交互式命令行
ld-elf.so.1: /lib/libcrypto.so.111: version OPENSSL_1_1_1e required by /usr/local/bin/node not found
```

> **注意**
>
> 上述错误信息中的 `libcrypto.so.111` 对应 OpenSSL 1.1.1（FreeBSD 13 及更早版本）。在 FreeBSD 14 中，基本系统的 OpenSSL 已升级至 3.x，对应的库文件为 `libcrypto.so.30`；FreeBSD 15 及更高版本中对应的库文件为 `libcrypto.so.35`。错误信息会有所不同，但根本原因相同：基本系统需要先更新。

Ports 会根据当前系统的库版本编译，因此使用 Ports 编译安装不会出现上述问题。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://book.bsdcn.org/di-40-zhang-kai-fa-huan-jing/di-40.7-jie-node-js-kai-fa-huan-jing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.