# @codesandbox/nodebox 中文文档

规范地址：https://npmcn.com/package/%40codesandbox/nodebox/

版本：0\.1\.9
npm 元数据更新时间：2025-04-29T15:22:48.906Z
中文译文更新时间：2026-11-10T07:50:56.566Z
软件包许可：SEE LICENSE IN \./LICENSE

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40codesandbox/nodebox
原文对照：https://npmcn.com/package/%40codesandbox/nodebox/?lang=original
项目主页：https://github.com/codesandbox/nodebox-runtime#readme
源码仓库：https://github.com/codesandbox/nodebox-runtime

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：102 kB，13 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2023-02-16T17:58:15.780Z
- 最新版本发布：2023-11-29T19:20:48.669Z
- 近 30 天下载量：6024436（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 0 个）

## 中文简介

节点的公开 API

## 安装

```sh
npm install @codesandbox/nodebox
```

也可以使用：`pnpm add @codesandbox/nodebox`、`yarn add @codesandbox/nodebox`、`bun add @codesandbox/nodebox`

## README

# 节点框

节点箱是执行浏览器中Node.js模块的运行时间.

## 为什么我们造节点箱

与 `sandpack-bundler`,我们允许任何开发者在任何地方立即在浏览器内创建一个快速,本地,可共享的游乐场,而无需等待永久安装依赖和与devtools战斗. 这改善了客户端JavaScript代码的学习,实验和经验交流.

然而,服务器侧JavaScript仍然是一个挑战. 在 CodeSandbox 我们用 [鞭炮 VMS](https://codesandbox.io/blog/how-we-clone-a-running-vm-in-2-seconds),让我们将你的整个开发环境带入云中,不管你可能使用何种编程语言或工具. 不幸的是,由于VMs生活在云中,它们需要基础设施和网络连接,因此与我们的客户端沙盒相比成本更高.

为了解决这个问题,我们建造了节点,这个运行时间完全运行在浏览器中,从而消除了网络连接和基础设施的需求.

节点框给您提供与Sandpack 相同的用户体验,这意味着在点击用于实验、实例和文档的按钮时,一个近即时服务器侧JavaScript环境.

## VM 和节点的区别

如上一节所提及,我们通过使用"鞭炮VM"来解决了CodeSandbox中的服务器侧沙盒. 本节将解释每种方法的利弊.

### VMs 对节点的优势

-   您得到专用资源, 没有浏览器强制实施的资源限制
-   您有一个完整的 Unix OS 可用
-   您可以运行任意语言、 数据库、 命令
-   您可以使用网络套接字
-   你可以运行大型和复杂的项目
-   与本地设置相比, 环境为 1: 1 (至少, 如果您使用基于 Unix 的系统)
-   所以Node.js的运行方式与本地完全相同

### 节点的优点

-   不需要任何基础设施
-   不需要网络连接
-   对任何变化的即时反馈
-   容易开始
-   容易即时重置 - 简单刷新页面/框架
-   每个页面访问者都会自动获得自己的节点箱实例

## 是什么让它不同

节点箱是目前唯一支持所有最新浏览器的交叉浏览器节点.js runtime:

-   克罗姆;
-   Firefox; (美国英语);
-   萨法里\*

> -   对iOS Safari的支持在β

节点框不模拟节点.js,而是是一个与节点.js相兼容的运行时间. 这意味着它尽可能多地执行节点.js API,同时保持最小的性能印记,在适用的情况下使用浏览器API,并在某些情况下由于浏览器而将节点.js的某些部分排除在外 [限制](https://npmcn.com/package/%40codesandbox/nodebox/#readme-Limitations) 或复杂.

节点框使用内部依赖性管理器,通过使用依赖性缓存通过微调来提供最佳初始负载时间 [沙子包装CDN](https://github.com/codesandbox/sandpack-cdn)CDN是一个开源的 Rust 软件包管理器,在云中运行,也可以很方便地自行托管.

虽然Nodebox有替代品,但它们更接近于模仿一个基于容器的环境,逐个运行命令,甚至整个Linux在您的浏览器中分布. 与"节点"相比,这使得它们使用速度更慢更难,而"节点"则被优化为能跑快地跑出沙盒,并尽可能少有摩擦.

## 限制

不幸的是,任何无法进入操作系统级API的运行时间都会受到一定的限制. 对于节点框,这些是:

-   N- API 模块
-   网络 # 指向外部IP
-   同步执行/弹出
-   aync hooks(计划执行)
-   自动进程退出 - 用户现在需要手动调用 `process.exit` 在该进程退出之前(计划执行)

当我们手动执行每个模块时,有些模块的行为可能不正确。 如果发生这种情况,请随意在GitHub上打开一个问题,我们将确保解决这个问题.

## 文档

-   [**开始**](https://npmcn.com/package/%40codesandbox/nodebox/#readme-getting-started)
-   [API 文档](https://github.com/codesandbox/nodebox-runtime/blob/main/packages/nodebox/api.md)

* * *

## 开始

节点框意在用于您的客户端应用程序,赋予它们直接在浏览器中运行实际节点.js代码的能力. 以下是节点盒何时可以被使用的一些例子:

-   在文档中创建服务器侧码的交互式示例;
-   显示用于构建的实际框架中的UI组件库;
-   一般来说,任何对Node.js代码的评价,并在浏览器中预览.

在这一辅导方面,我们将建立一个文件网站,说明使用Next.js应用程序的不同例子。 铭记我们的文件本身可在我们所选择的任何框架内编写.

### 安装

节点箱可以像其他依赖者一样从国家预防机制安装:

```sh
npm install @codesandbox/nodebox
```

### 设置

节点箱由两个主要部分组成:

-   评估代码的运行时间环境;
-   为评价结果服务的一个预览环境.

与这两个部分相对应,让我们在应用程序中创建两个iframe:

```html
<!--
  The "nodebox" iframe will mount the Nodebox runtime,
  allowing it to communicate with the rest of the application.
-->
<iframe id="nodebox-iframe"></iframe>

<!--
  The "preview" iframe will contain the result of running
  the Next.js example we will configure in a moment.
-->
<iframe id="preview-iframe"></iframe>
```

虽然运行时环境可以自行托管,但我们会在CodeSandbox服务器上使用默认指向已部署的节点实例的. 但是,我们确实需要具体说明: `iframe` 在我们的应用程序中,当节点显示其预览.

```js
import { Nodebox } from '@codesandbox/nodebox';

const runtime = new Nodebox({
  // Provide a reference to the <iframe> element in the DOM
  // where Nodebox should render the preview.
  iframe: document.getElementById('nodebox-iframe'),
});

// Establish a connection with the runtime environment.
await runtime.connect();
```

> 学习更多关于 [节点框 API](https://github.com/codesandbox/nodebox-runtime/blob/main/packages/nodebox/api.md)。 。 。 .

你想建立 **单一节点实例** 整个申请。 在设立阶段铭记这一点,并参考你框架的文件和关于实现这一目标的最有效方式的最佳做法.

预览对应 _命令_ 在节点框中执行,这意味着在此阶段将不会在给定的iframe上挂载预览,因为我们还没有运行任何命令. 让我们改变这一点.

### 初始化文件系统

和你自己的项目一样,您在节点中创建的项目需要文件来配合. 它可以是单个JavaScript文件或整个项目,如Astro或Next.js.

让我们描述下个J项目 我们需要它.

```js
// Populate the in-memory file system of Nodebox
// with a Next.js project files.
await runtime.fs.init({
  'package.json': JSON.stringify({
    name: 'nextjs-preview',
    dependencies: {
      '@next/swc-wasm-nodejs': '12.1.6',
      next: '12.1.6',
      react: '18.2.0',
      'react-dom': '18.2.0',
    },
  }),
  // On the index page, let's illustrate how server-side props
  // propagate to your page component in Next.js.
  'pages/index.jsx': `
export default function Homepage({ name }) {
  return (
    <div>
      <h1>Hello, {name}</h1>
      <p>The name "{name}" has been received from server-side props.</p>
    </div>
  )
}

export function getServerSideProps() {
  return {
    props: {
      name: 'John'
    }
  }
}
    `,
});
```

> 您可以在撰写工程文件时参考标准Node.js模块以及外部依赖性. 请注意你 **不用装了** 作为节点框的这些依赖性会自动管理依赖性安装,缓存和解析.

我们在上面所做的是,为节点箱运行而勾画一个实际 Next.js 工程的文件系统状态 。 剩下的最后一步是运行Next.js.

### 运行项目

为了管理这个项目,我们将运行 `npm dev` 命令使用由节点提供的 Shell API.

```js
// First, create a new shell instance.
// You can use the same instance to spawn commands,
// observe stdio, restart and kill the process.
const shell = runtime.shell.create();

// Then, let's run the "dev" script that we've defined
// in "package.json" during the previous step.
const nextProcess = await shell.runCommand('npm', ['dev']);

// Find the preview by the process and mount it
// on the preview iframe on the page.
const previewInfo = await runtime.preview.getByShellId(nextProcess.id);
const previewIframe = document.getElementById('preview-iframe');
previewIframe.setAttribute('src', previewInfo.url);
```

> 请注意,你可以治疗 `shell.runCommand` 类似 `spawn` 在节点.js。 了解更多关于壳牌API的 [文档](https://github.com/codesandbox/nodebox-runtime/blob/main/packages/nodebox/api.md)。 。 。 .

此命令运行后, 它会返回一个我们能用来检索预览 URL 的 shell 引用 。 通过将预览 URL 从设置中挂入我们的预览 iframe, 我们可以看到 Next.js 项目运行 :

![](https://github.com/codesandbox/nodebox-runtime/blob/main/packages/nodebox/nextjs-preview.png)

就这样 **运行此 Next.js 应用程序时, 没有一个服务器被生成**。所有东西都由节点直接在浏览器中管理.

看看这个 [此教程的沙盒](https://codesandbox.io/p/sandbox/nodebox-next-js-example-ji27x8)。 。 。 .

## 常见问题

### @codesandbox/nodebox 是什么？

节点的公开 API

### 如何安装 @codesandbox/nodebox？

在项目目录运行 npm install @codesandbox/nodebox，或使用 pnpm add / yarn add / bun add。

### @codesandbox/nodebox 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @codesandbox/nodebox 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @codesandbox/nodebox 可以商用吗？

@codesandbox/nodebox 使用 SEE LICENSE IN \./LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @codesandbox/nodebox 的下载量有多少？

根据 npm 官方下载统计，@codesandbox/nodebox 在 2026/10/10 – 2026/11/08 这 30 天内被下载 6,024,436 次，日均约 200,815 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @codesandbox/nodebox 还在维护吗？

最新版本 0\.1\.9 发布于 2023/11/30（2 年前）；至今共发布 10 个版本，其中过去 12 个月发布了 0 个；首次发布于 2023/02/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。