跳到主要内容

安装与命令行使用教程

本指南介绍如何安装 Sii 语言工具链与使用命令行 sii 完成编译与运行，并提供常见问题排查。

1. 环境要求​

  • Node.js ≥ 16（建议最新 LTS）
  • npm ≥ 8（或使用 pnpm/yarn，命令请自行替换）

检查版本：

node -v
npm -v

2. 安装​

  • 全局安装（推荐）：
npm i -g @andyjinxi/sii-lang

验证安装（应显示版本号）：

sii -v
# 输出示例：1.0.2

提示：如出现 command not found: sii，请参考“故障排查”。

3. 基础用法​

3.1 运行 .sii 文件​

sii run path/to/main.sii
# 输出示例：
# Hello, Sii!

3.2 编译为TS​

可以快速编译为TS，提升兼容性。

# 编译到 out/ 目录（若省略 -o，使用默认的 dist/）
sii compile path/to/main.sii -o out
# 输出示例：
# ✔ 编译成功：out/main.js

3.3 指定目标与调试信息（可选）​

# 指定输出语言（js/ts），默认 js
sii compile app.sii --target js

# 输出 SourceMap（若支持）
sii compile app.sii --sourcemap

3.4 显示帮助​

sii --help
# 输出示例（根据版本略有不同）：
# 用法：
#   sii run <file.sii>
#   sii compile <file.sii> [-o <dir>] [--target js|ts] [--sourcemap]
#   sii -v | --version
#   sii -h | --help

4. 示例：从 0 到 1​

新建 hello.sii：

func greet(name: string): string { back "Hello, " + name + "!"; }
back greet("Sii") => say;
print(say);

运行：

sii run hello.sii
# 输出：
# Hello, Sii!

编译：

sii compile hello.sii -o dist
# 输出：
# ✔ 编译成功：dist/hello.js

5. 跨平台说明​

  • macOS / Linux：终端为 bash/zsh/sh，sii 安装后通常位于 /usr/local/bin 或 ~/.npm-global/bin。
  • Windows：在 PowerShell 或 CMD 中使用；sii 会进入系统 PATH 对应的 npm global bin 目录（如 AppData\Roaming\npm）。

6. 故障排查（FAQ）​

  • 问：command not found: sii 或 sii 不是内部或外部命令

    • 解：确认全局安装成功：npm i -g @andyjinxi/sii-lang
    • 查看 npm 全局 bin：npm bin -g，将该目录加入环境变量 PATH。
    • macOS 常见：echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.zshrc && source ~/.zshrc

  • 问：EACCES: permission denied（macOS/Linux）

    • 解：不要使用 sudo npm i -g；建议配置 npm 全局目录到用户空间： 
      mkdir -p ~/.npm-global
      npm config set prefix '~/.npm-global'
      echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
      source ~/.zshrc
      npm i -g @andyjinxi/sii-lang

  • 问：报错 Cannot find module 'readline-sync'

    • 解：新版已内置兼容；如仍遇到，请安装依赖：npm i -g readline-sync 或本地安装到项目后再运行。

  • 问：运行/编译但无输出或编码异常

    • 解：确保终端使用 UTF-8；输入读取时回车会提交一行，非 ASCII 文本需确保终端编码一致。

7. 版本与升级​

查看版本：

sii -v

升级到最新：

npm i -g @andyjinxi/sii-lang@latest

8. 与桌面版 SiiDeal 的关系​

  • 桌面版集成了编辑器、文件管理与终端；适合图形化工作流。
  • CLI 适合脚本化/CI 等场景；两者可配合使用（同一份代码、一致的语言能力）。