sandbox-npm-install

沙箱 npm 安装

何时使用此技能

在以下任何情况下使用此技能：

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

前提条件

• 带有 virtiofs 挂载工作区的 Docker 沙箱环境
• 容器中可用的 Node.js 和 npm
• 目标工作区中有 package.json 文件

背景

Docker 沙箱工作区通常通过 virtiofs 挂载（主机与 Linux VM 之间的文件同步）。在 aarch64 上从 virtiofs 执行时，原生 Go 和 Rust 二进制文件（esbuild、lightningcss、rollup 等）会因 mmap 对齐失败而崩溃。修复方法是在容器的本地 ext4 文件系统上安装，并软链接回工作区。

分步安装

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

bash scripts/install.sh

常用选项

选项	描述
--workspace <path>	包含 package.json 的目录路径（省略时自动检测）
--playwright	同时安装 Playwright Chromium 浏览器以进行 E2E 测试

脚本的作用

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

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

安装后验证

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

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

重要说明

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

故障排除

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

Vite 兼容性

如果你的项目使用 Vite，你可能需要在 server.fs.allow 中允许软链接路径。将软链接目标的父目录（例如 /home/agent/project-deps/）添加到你的 Vite 配置中，以便 Vite 可以通过软链接提供文件。