sandbox-npm-install

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sandbox npm Install

沙箱环境npm安装

When to Use This Skill

何时使用此方法

Use this skill whenever:

You need to install npm packages for the first time in a new sandbox session
```
package.json
```
or
```
package-lock.json
```
has changed and you need to reinstall
You encounter native binary crashes with errors like
```
SIGILL
```
,
```
SIGSEGV
```
,
```
mmap
```
, or
```
unaligned sysNoHugePageOS
```
The
```
node_modules
```
directory is missing or corrupted

当你遇到以下情况时使用：

需要在新的沙箱会话中首次安装npm包
```
package.json
```
或
```
package-lock.json
```
已更改，需要重新安装
遇到原生二进制文件崩溃，错误如
```
SIGILL
```
、
```
SIGSEGV
```
、
```
mmap
```
或
```
unaligned sysNoHugePageOS
```
```
node_modules
```
目录缺失或损坏

Prerequisites

前置条件

A Docker sandbox environment with a virtiofs-mounted workspace
Node.js and npm available in the container
A
```
package.json
```
file in the target workspace

带有通过virtiofs挂载工作区的Docker沙箱环境
容器内已安装Node.js和npm
目标工作区中存在
```
package.json
```
文件

Background

背景

Docker sandbox workspaces are typically mounted via virtiofs (file sync between the host and Linux VM). Native Go and Rust binaries (esbuild, lightningcss, rollup, etc.) crash with mmap alignment failures when executed from virtiofs on aarch64. The fix is to install on the container's local ext4 filesystem and symlink back into the workspace.

Docker沙箱工作区通常通过virtiofs（主机与Linux虚拟机之间的文件同步）挂载。原生Go和Rust二进制文件（如esbuild、lightningcss、rollup等）在aarch64架构的virtiofs上执行时，会因mmap对齐失败而崩溃。解决方法是将包安装在容器的本地ext4文件系统中，再创建符号链接回工作区。

Step-by-Step Installation

分步安装步骤

Run the bundled install script from the workspace root:

bash

bash scripts/install.sh

从工作区根目录运行捆绑的安装脚本：

bash

bash scripts/install.sh

Common Options

常用选项

Option	Description
`--workspace <path>`	Path to directory containing `package.json` (auto-detected if omitted)
`--playwright`	Also install Playwright Chromium browser for E2E testing

选项	描述
`--workspace <path>`	包含 `package.json` 的目录路径（如果省略则自动检测）
`--playwright`	同时安装Playwright Chromium浏览器以用于端到端测试

What the Script Does

脚本执行的操作

Copies
```
package.json
```
,
```
package-lock.json
```
, and
```
.npmrc
```
(if present) to a local ext4 directory
Runs
```
npm ci
```
(or
```
npm install
```
if no lockfile) on the local filesystem
Symlinks
```
node_modules
```
back into the workspace
Verifies known native binaries (esbuild, rollup, lightningcss, vite) if present
Optionally installs Playwright browsers and system dependencies (uses
```
sudo
```
when available)

If verification fails, run the script again — crashes can be intermittent during initial setup.

将
```
package.json
```
、
```
package-lock.json
```
和
```
.npmrc
```
（如果存在）复制到本地ext4目录
在本地文件系统上运行
```
npm ci
```
（如果没有锁文件则运行
```
npm install
```
）
将
```
node_modules
```
符号链接回工作区
如果存在已知原生二进制文件（esbuild、rollup、lightningcss、vite），则进行验证
可选安装Playwright浏览器和系统依赖项（如果可用则使用
```
sudo
```
）

如果验证失败，请重新运行脚本——初始设置期间崩溃可能是间歇性的。

Post-Install Verification

安装后验证

After the script completes, verify your toolchain works. For example:

bash

npm test             # Run project tests
npm run build        # Build the project
npm run dev          # Start dev server

脚本完成后，验证你的工具链是否正常工作。例如：

bash

npm test             # 运行项目测试
npm run build        # 构建项目
npm run dev          # 启动开发服务器

Important Notes

重要注意事项

The local install directory (e.g.,
```
/home/agent/project-deps
```
) is container-local and is NOT synced back to the host
The
```
node_modules
```
symlink appears as a broken link on the host — this is harmless since
```
node_modules
```
is typically gitignored
Running
```
npm ci
```
or
```
npm install
```
on the host naturally replaces the symlink with a real directory
After any
```
package.json
```
or
```
package-lock.json
```
change, re-run the install script
Do NOT run
```
npm ci
```
or
```
npm install
```
directly in the mounted workspace — native binaries will crash

本地安装目录（例如
```
/home/agent/project-deps
```
）是容器本地的，不会同步回主机
在主机上
```
node_modules
```
符号链接显示为损坏的链接——这是无害的，因为
```
node_modules
```
通常会被git忽略
在主机上运行
```
npm ci
```
或
```
npm install
```
会自然地将符号链接替换为真实目录
任何
```
package.json
```
或
```
package-lock.json
```
更改后，重新运行安装脚本
不要在挂载的工作区中直接运行
```
npm ci
```
或
```
npm install
```
——原生二进制文件会崩溃

Troubleshooting

故障排除

Problem	Solution
`SIGILL` or `SIGSEGV` when running dev server	Re-run the install script; ensure you're not running `npm install` directly in the workspace
`node_modules` not found after install	Check that the symlink exists: `ls -la node_modules`
Permission errors during install	Ensure the local deps directory is writable by the current user
Verification fails intermittently	Run the script again — native binary crashes can be non-deterministic on first load

问题	解决方案
运行开发服务器时出现 `SIGILL` 或 `SIGSEGV`	重新运行安装脚本；确保不要在工作区中直接运行 `npm install`
安装后找不到 `node_modules`	检查符号链接是否存在： `ls -la node_modules`
安装期间出现权限错误	确保本地依赖目录对当前用户可写
验证间歇性失败	重新运行脚本——原生二进制文件在首次加载时的崩溃可能是非确定性的

Vite Compatibility

Vite兼容性

If your project uses Vite, you may need to allow the symlinked path in

server.fs.allow

. Add the symlink target's parent directory (e.g.,

/home/agent/project-deps/

) to your Vite config so that Vite can serve files through the symlink.

如果你的项目使用Vite，你可能需要在

server.fs.allow

中允许符号链接路径。将符号链接目标的父目录（例如

/home/agent/project-deps/

）添加到你的Vite配置中，以便Vite可以通过符号链接提供文件。