跳到主要内容

安装与 CLI

本章介绍如何安装 Sii、创建项目、运行与构建。

环境要求​

  • Node.js ≥ 20
  • npm ≥ 10（或等价包管理器）

安装​

全局安装 CLI（建议）：

npm i -g @andyjinxi/sii-lang

或项目内安装：

npm i -D @andyjinxi/sii-lang

验证版本：

sii --version

快速创建​

Sii 提供两种项目初始化方式：

基础项目​

创建最小可运行的Sii项目：

sii init my-sii-app
cd my-sii-app
npm install

Web项目​

创建SiiUI Web项目：

sii init-web my-web-app
cd my-web-app
npm install

项目类型说明：

  • init：基础Sii项目，包含CLI脚本和基础示例
  • init-web：SiiUI Web项目，包含页面结构和UI组件示例

目录结构​

基础项目结构​

my-sii-app/
  src/
    index.sii
  package.json
  README.md

Web项目结构​

my-web-app/
  pages/
    index.sii
  assets/
    images/
    icons/
    media/
  dist/
    pages/
  package.json

命令总览​

CLI 入口：sii。主要子命令：

编译：sii compile <input>​

  • <input>：必填，.sii 源文件路径
  • -o, --output <path>：可选，输出文件路径（默认同目录同名，.ts 或 .js）
  • -t, --target <type>：typescript | javascript，默认 typescript
  • --source-map：生成 Source Map（当目标为 JS/TS 时有效）

示例：

sii compile src/index.sii -o dist/index.ts
sii compile src/index.sii --target javascript

运行：sii run [input] 和 sii run --web <projectDir>​

基础运行模式​

  • sii run <input>：编译并运行单个Sii文件
  • <input>：必填，.sii 源文件路径
  • -t, --target <type>：编译目标 typescript（默认）

示例：

sii run src/index.sii
sii run src/index.sii --target typescript

Web项目模式​

  • sii run --web <projectDir>：以Web项目模式运行
  • --serve：构建完成后启动本地预览服务器（默认端口5173）
  • --build：仅构建，不启动服务器

示例：

# 构建Web项目
sii run --web MySite --build

# 构建并启动预览服务器
sii run --web MySite --serve

初始化项目：sii init <name> 和 sii init-web <name>​

  • sii init <name>：创建基础Sii项目
  • sii init-web <name>：创建SiiUI Web项目
  • 自动生成 package.json、示例代码与脚本

示例：

# 创建基础项目
sii init hello-sii
cd hello-sii && npm i && sii run hello-sii/index.sii

# 创建Web项目
sii init-web hello-web
cd hello-web && npm i && sii run --web hello-web --serve

库管理命令​

提示

版本要求：该功能从 v1.2.1 开始支持

Sii 已经支持开发者提交自定义编写的第三方库，经审核后将上传至库中心，完整支持的所有库可以前往库中心查看

安装库：sii install <library>​

安装指定的库到本地库目录。

直接安装最新版本​

使用sii install <library>可以直接安装最新版本

# 以安装 math 库为例
sii install math
安装指定版本​

使用sii install <library>:<version>可以安装指定版本的库

sii install math:0.0.1

查看已安装库：sii list​

以表格形式显示所有已安装的库及其版本信息。

sii list

输出示例：

已安装的库:

库名     版本
——————————————
math    0.0.1
others  0.0.2

更新库：sii update-lib [library]​

更新指定库到最新版本，或更新所有库。

# 更新指定库
sii update-lib math

# 更新指定库到特定版本
sii update-lib math:0.0.2

# 更新所有库
sii update-lib

卸载库：sii uninstall <library>​

卸载指定的库及其所有版本。

sii uninstall math

查看库版本：sii versions <library>​

显示指定库的所有可用版本信息。

sii versions math

输出示例：

库名: math
描述: math library for SII language
最新版本: 0.0.2
总版本数: 3

版本列表:
  1. 0.0.2 (最新)
  2. 0.0.1
  3. 0.0.0

系统更新：sii update​

提示

版本要求：该功能从 v1.2.1 开始支持

更新 Sii CLI 到最新版本。

# 检查更新（仅检查，不执行更新）
sii update --check-only

# 强制更新到最新版本
sii update --force

# 普通更新（如果已是最新版本则跳过）
sii update

语言设置：sii language​

提示

版本要求：该功能从 v1.2.1 开始支持

设置 CLI 的显示语言。

# 查看当前语言
sii language --current

# 查看可用语言
sii language --list

# 设置语言为中文
sii language --set zh-CN

# 设置语言为英文
sii language --set en

镜像源管理：sii mirror​

提示

版本要求：该功能从 v1.2.1 开始支持

管理库下载的镜像源，用于加速库的下载或使用自定义镜像源。目前第三方库使用频度较少，因此只在本平台构建镜像地址，并未在其他平台构建镜像。

添加镜像源：sii mirror --add "<name> <url>"​

添加新的镜像源。name参数可以自定义命名。

# 添加自定义镜像源
sii mirror --add "custom https://example.com/lib"

查看镜像源：sii mirror --list​

显示所有已配置的镜像源。

sii mirror --list

输出示例：

可用的镜像源:
  default: https://sii.andyjin.website/lib (默认)
  custom: https://example.com/lib

设置默认镜像源：sii mirror --set-default <name>​

设置默认使用的镜像源。

# 设置custom为默认镜像源
sii mirror --set-default custom

查看当前镜像源：sii mirror --current​

显示当前正在使用的镜像源。

sii mirror --current

移除镜像源：sii mirror --remove <name>​

移除指定的镜像源，但不能移除默认镜像源。

sii mirror --remove custom

镜像源URL格式说明​

镜像源地址需要包含完整的库文件路径，下载时会自动拼接 /库名.sii。

例如：

  • 正确格式：https://example.com/lib
  • 下载时会访问：https://example.com/lib/math/math-0.0.1.sii

版本信息：sii version​

打印版本与标语等信息。

sii version

常见错误与返回码​

  • 输入文件不存在：返回码 1，并输出红色错误信息
  • 编译失败：返回码 1，打印格式化错误列表
  • 运行子进程异常：返回非 0，并清理临时文件