文档

安装

NSH 的所有操作都通过一个命令 nsh 完成：打包和编译应用、运行开发服务器、启动开发宿主、打包可安装的应用。你可以使用无需 Rust 的预构建发行包，也可以从仓库源码构建。

除了 nsh 本身，每个平台还需要自己的工具：

平台	在哪里开发和打包	需要
iOS	macOS	Xcode 和一个 iOS 模拟器运行时
Android	macOS、Windows 或 Linux	Android SDK 和 JDK；一个模拟器或设备
macOS	macOS	Xcode 命令行工具；应用运行在 macOS 14+
Windows	Windows	Windows 10 1809+；网页视图需要 WebView2 Runtime
Linux	Linux	GTK 4.14+（构建运行时还需要它的开发包）
GPUI	macOS、Windows 或 Linux，为该系统打包	GPU（Metal、DirectX 或 Vulkan）；Linux 上需要 Wayland 或 X11

macOS 上 nsh run 的默认目标 Mac Catalyst 和 iOS 一样需要 Xcode。详见平台工具。

#安装发布版本

每个 GitHub release 都附带 macOS（Apple silicon）、Linux x86_64 和 Windows x86_64 的预构建发行包（见下文）。无论用哪种方式安装，PATH 上得到的都是同一个 nsh 命令。

macOS 和 Linux，使用安装脚本：

curl -fsSL https://nsh.dev/install.sh | sh

它把发行包安装到 ~/.nsh，并把 ~/.local/bin/nsh 链接过去；再次运行即可更新。NSH_VERSION=v0.1.0 指定版本，NSH_INSTALL_DIR 指定其他目录。

Windows，在 PowerShell 中：

irm https://nsh.dev/install.ps1 | iex

它安装到 %LOCALAPPDATA%\nsh，并把其中的 bin 加入用户 PATH（之后打开新的终端）。$env:NSH_VERSION 和 $env:NSH_INSTALL_DIR 的用法同上。

Homebrew（macOS 和 Linux）：

brew install longbridge/tap/nsh

Scoop（Windows）：

scoop install https://github.com/longbridge/nsh/releases/latest/download/nsh.json

mise（三个平台）：

mise use -g github:longbridge/nsh

压缩包（nsh-macos-arm64.tar.gz、nsh-linux-x86_64.tar.gz、nsh-windows-x86_64.zip，各带一个 .sha256）的文件名不含版本号，所以 https://github.com/longbridge/nsh/releases/latest/download/<压缩包> 总是下载最新版本。嵌入用的 SDK 也单独发布，供不需要 CLI 的原生应用使用：nsh-embed-ios.zip 和 nsh-embed-android.zip。

#预构建发行包

发行包是一个目录 dist/nsh，包含 CLI 以及它打包应用时使用的预构建原生运行时：

dist/nsh/bin/nsh                                             # the CLI
dist/nsh/runtime/ios/iphoneos/nsh-ios-app                    # runs packaged apps on iOS devices
dist/nsh/runtime/ios/iphonesimulator/{nsh-ios-app,nsh-ios-host}
dist/nsh/runtime/ios/maccatalyst/nsh-ios-host                # the Mac Catalyst development host
dist/nsh/runtime/android/{release,dev}/                      # classes.dex, lib/<abi>/libnsh.so
dist/nsh/runtime/macos/{nsh-macos-host,nsh-macos-app}        # the macOS (AppKit) development host and release runner
dist/nsh/runtime/linux/{nsh-linux-host,nsh-linux-app}        # the Linux development host and release runner
dist/nsh/runtime/windows/{nsh-windows-host,nsh-windows-app}.exe  # the Windows development host and release runner
dist/nsh/runtime/gpui/{nsh-gpui-host,nsh-gpui-app}[.exe]     # the GPUI development host and release runner, for this OS
dist/nsh/runtime/web/{nsh.wasm,nsh-dev.wasm,nsh.js}          # the web runtimes (nsh package / run --target web)
dist/nsh/embed/ios/{NativeShell,NativeShellDev}.xcframework  # embedding in iOS apps
dist/nsh/embed/android/{nsh,nsh-dev}.aar                     # embedding in Android apps

把 dist/nsh/bin 加入 PATH（或直接调用 dist/nsh/bin/nsh），并保持目录完整：nsh 会在自身旁边的 bin/../runtime 中查找运行时（通过指向它的符号链接运行时也一样，安装脚本就是这样做的）。

export PATH="$PWD/dist/nsh/bin:$PATH"
nsh --version

发行包由源码仓库中的 cargo xtask dist 生成（见下文）。其中的 nsh 可执行文件是为该机器构建的。在装有 Xcode 的 Mac 上，它包含 iOS 和 macOS 运行时（Apple Silicon）；在 Linux 上，它改为包含为该机器构建的 Linux 运行时；在 Windows 上则包含 Windows 运行时，CLI 为 bin\nsh.exe。每个发行包还包含为该机器构建的 GPUI 运行时。它们都包含 Android 运行时（在 Windows 上，只有找到 Android SDK 时才包含）。

#从源码构建

你需要通过 rustup 安装 Rust。仓库中的 rust-toolchain.toml 会选择 stable 工具链，并在首次使用时安装 iOS 和 Android 目标。

git clone https://github.com/longbridge/nsh.git
cd nsh
cargo build -p nsh-cli          # ./target/debug/nsh

然后为每个要运行的目标构建开发宿主，构建一次即可，更新源码后再重新构建：

cargo build -p nsh-ios-host --target aarch64-apple-ios-macabi   # nsh run (Mac Catalyst window)
cargo build -p nsh-ios-host --target aarch64-apple-ios-sim      # nsh run --target ios
cargo xtask android --dev                                       # nsh run --target android
cargo build -p nsh-macos-host                                   # nsh run --target macos (built for you in a checkout)
cargo build -p nsh-linux-host                                   # nsh run on Linux (built for you in a checkout)
cargo build -p nsh-windows-host                                 # nsh run on Windows (built for you in a checkout)
cargo build --manifest-path crates/gpui/Cargo.toml --target-dir target -p nsh-gpui-host   # nsh run --target gpui (built for you in a checkout)
cargo build --profile web -p nsh-platform-web --target wasm32-unknown-unknown   # nsh run --target web (built for you in a checkout)

如果要使用 nsh package，还需要构建发布版运行器：

cargo build -p nsh-ios-app --target aarch64-apple-ios-sim       # nsh package --target ios-simulator
cargo build -p nsh-ios-app --target aarch64-apple-ios           # nsh package --target ios
cargo xtask android                                             # nsh package --target android
cargo build -p nsh-macos-app                                    # nsh package --target macos
cargo build -p nsh-linux-app                                    # nsh package --target linux
cargo build -p nsh-windows-app                                  # nsh package --target windows
cargo build --manifest-path crates/gpui/Cargo.toml --target-dir target -p nsh-gpui-app    # nsh package --target gpui
# nsh package --target web uses the same web runtime as nsh run --target web

从源码构建的 CLI 会按自身的 profile 在 target/<triple>/<profile>（macOS、Linux、Windows 和 GPUI 运行时为本机构建，位于 target/<profile>）和 target/android/<profile>[-dev] 中查找运行时：./target/debug/nsh 使用 debug 运行时，./target/release/nsh 使用 release 运行时。请用相同的 profile 构建两者（若希望应用更快，给所有命令都加上 --release）。

#平台工具

#iOS 与 Mac Catalyst

Xcode（及其命令行工具）。nsh run 用 xcrun simctl 启动模拟器并安装开发宿主；nsh package 用 actool 处理应用图标，用 codesign 签名。
一个 iOS 模拟器运行时。如果还没有安装，可以用 xcodebuild -downloadPlatform iOS 安装。
应用支持 iOS 15.0 及以上版本。

#Android

Android SDK，通过 ANDROID_HOME、ANDROID_SDK_ROOT 或 Android Studio 的默认位置（~/Library/Android/sdk，Windows 上为 %LOCALAPPDATA%\Android\Sdk）查找，需包含：
- platforms;android-35 和较新的 build-tools（NSH 使用其中的 aapt2、zipalign 和 apksigner，不使用 Gradle）；
- platform-tools（adb）。
JDK（首次打包时 keytool 会在 ~/.android/debug.keystore 创建调试密钥库，apksigner 也需要 Java）。
一个正在运行的模拟器，或通过 adb 连接的设备。应用要求 Android 9（API 28）及以上。

sdkmanager "platforms;android-35" "build-tools;35.0.1" "platform-tools"

#macOS

Xcode 命令行工具（xcode-select --install）：构建运行时需要其中的 SDK 和 clang，打包应用需要 codesign 和 sips。
应用要求 macOS 14 及以上。

见 macOS。

#Linux

GTK 4.14 及以上；构建运行时还需要它们的开发包和 clang：libgtk-4-dev clang（Debian、Ubuntu 24.04 及以上）、gtk4 clang（Arch）、gtk4-devel clang（Fedora）。
Web 视图需要 WebKitGTK 6.0（2.40 及以上）：构建运行时需要 libwebkitgtk-6.0-dev（Debian、Ubuntu）、webkitgtk-6.0（Arch）、webkitgtk6.0-devel（Fedora），应用运行的机器上也需要它。没有它时，cargo xtask dist 构建的运行时中 Web 视图为占位视图。
应用要播放的视频格式对应的 GStreamer 插件。

见 Linux。

#Windows

Windows 10 1809 及以上，或 Windows 11。Web 视图需要 WebView2 Runtime（Windows 11 自带，Windows 10 上随 Edge 安装）。
构建运行时需要：带“使用 C++ 的桌面开发”工作负载的 Visual Studio Build Tools 和 Windows SDK，以及 LLVM（libclang，用于生成 QuickJS 的绑定；默认在 C:\Program Files\LLVM 中查找，否则请设置 LIBCLANG_PATH）。

见 Windows。

#构建 Android 运行时

从源码构建 Android 运行时（cargo xtask android）还需要 SDK 中的 NDK（ndk;<version>；如果已安装的最新版本不完整，请设置 ANDROID_NDK_HOME）以及 javac。

#各平台可用的命令

命令	macOS	Linux	Windows
`nsh init`, `nsh build`, `nsh trace`, `nsh dev`, `nsh check`	可以	可以	可以
`nsh run`（Mac Catalyst，macOS 上的默认目标）	可以	不可以	不可以
`nsh run --target macos`, `nsh package --target macos`	可以	不可以	不可以
`nsh run --target linux`（Linux 上的默认目标）, `nsh package --target linux`	不可以	可以	不可以
`nsh run --target windows`（Windows 上的默认目标）, `nsh package --target windows`	不可以	不可以	可以
`nsh run --target gpui`, `nsh package --target gpui`（为打包所在的系统打包）	可以	可以	可以
`nsh run --target ios`, `nsh package --target ios` / `ios-simulator`	可以，需要 Xcode	不可以	不可以
`nsh run --target android`, `nsh package --target android`	可以	可以，需从源码构建	可以，需有 Android 运行时
`nsh keygen`, `certify`, `publish`, `verify`, `revoke`	可以	可以	可以

在 Linux 上，请从源码构建 CLI 和 Android 运行时（cargo build -p nsh-cli 与 cargo xtask android --dev）；会自动使用 NDK 的 Linux 工具链。在 Windows 上同样会使用 NDK 的 Windows 工具链，cargo xtask dist 找到 Android SDK 时会包含 Android 运行时。

#编辑器配置

NSH 无需 NPM。nsh init 会写入 tsconfig.json，并把 NSH 提供的所有内容的类型声明写入 .nsh/types，之后每个构建应用的命令都会让它们保持最新。任何使用 TypeScript 语言服务的编辑器（VS Code、Zed、Neovim、WebStorm）都能借此对应用做类型检查。参见项目结构。

#下一步

继续阅读快速开始，创建并运行一个应用。