Spire 天擎

外观

快速开始 ​

本指南基于 Windows x86_64 平台，带你从零完成环境搭建并运行第一个 Spire 应用。

视频教程：从零开始搭建 Spire 应用

一、安装仓颉 SDK 与 VS Code 插件 ​

前往仓颉 SDK 下载页面，下载 1.1.0 SDK 安装包及最新版 VS Code 插件（.vsix 文件）。

安装 SDK： 按向导完成安装，默认安装至 C:\Program Files (x86)\Cangjie，安装程序会自动写入以下环境变量：

  • CANGJIE_HOME → SDK 根目录
  • PATH → 追加 %CANGJIE_HOME%\bin

安装完成后，打开新终端验证：

bash
cjc --version
cjpm --version

安装 VS Code 插件： 在 VS Code 中通过「从 VSIX 安装」方式安装下载好的 .vsix 文件，随后在插件设置中将 SDK 路径指向 %CANGJIE_HOME%，即可获得语法高亮与代码补全支持。

二、安装 STDX 扩展标准库 ​

前往 cangjie_stdx 仓库 下载与 SDK 版本对应的压缩包，解压至本地目录。

压缩包内层结构为 windows_x86_64_cjnative\static\stdx，CANGJIE_STDX_PATH 需指向其中的 stdx 子目录。

在系统环境变量中新增以下配置（控制面板 → 系统 → 高级系统设置 → 环境变量）：

变量名值示例说明
CANGJIE_STDX_PATHD:\cangjiestdx\windows_x86_64_cjnative\static\stdx指向解压目录中的 stdx 子目录

三、安装 OpenSSL ​

Spire 的 TLS / JWT 功能依赖 OpenSSL。前往 slproweb Win32/Win64 OpenSSL，下载 Win64 OpenSSL Light 安装包，按向导完成安装即可。

四、创建第一个 Spire 应用 ​

1. 初始化项目 ​

创建项目目录并使用 cjpm 初始化：

bash
mkdir web
cd web
cjpm init

初始化完成后，项目结构如下：

web/
  ├── cjpm.toml
  └── src/
      └── main.cj

2. 修改 cjpm.toml ​

将 cjpm.toml 替换为以下内容：

toml
[package]
  cjc-version = "1.1.0"
  name = "web"
  description = ""
  version = "1.0.0"
  target-dir = ""
  src-dir = ""
  output-type = "executable"
  compile-option = ""
  override-compile-option = ""
  link-option = ""
  package-configuration = {}

[dependencies]
  soulsoft_web_http = "1.0.20260401"
  soulsoft_web_routing = "1.0.20260401"
  soulsoft_web_hosting = "1.0.20260401"
  soulsoft_extensions_injection = "1.0.20260401"

[target]
  [target.x86_64-w64-mingw32]
    compile-option = "-Woff unused --diagnostic-format=noColor -Woff deprecated -lcrypt32 -lcangjie-dynamicLoader-opensslFFI"
    [target.x86_64-w64-mingw32.bin-dependencies]
      path-option = [ "${CANGJIE_STDX_PATH}" ]
  [target.x86_64-unknown-linux-gnu]
    compile-option = "-Woff unused --diagnostic-format=noColor -Woff deprecated -ldl"
    [target.x86_64-unknown-linux-gnu.bin-dependencies]
      path-option = [ "${CANGJIE_STDX_PATH}" ]
  [target.aarch64-unknown-linux-gnu]
    compile-option = "-Woff unused --diagnostic-format=noColor -Woff deprecated -ldl"
    [target.aarch64-unknown-linux-gnu.bin-dependencies]
      path-option = [ "${CANGJIE_STDX_PATH}" ]

Windows 链接说明

Windows 目标的 compile-option 中必须保留 -lcangjie-dynamicLoader-opensslFFI。缺少该参数会在链接阶段报 undefined symbol: DYN_SHA1 错误，这是 SDK 1.1.0 在 Windows 下的已知问题。

3. 修改 src/main.cj ​

cangjie
package web

import soulsoft_web_http.*
import soulsoft_web_routing.*
import soulsoft_web_hosting.*
import soulsoft_extensions_injection.*

main(args: Array<String>): Int64 {
    let builder = WebHost.createBuilder(args)
    builder.services.addRouting()

    let host = builder.build()
    host.useRouting()

    host.mapGet("hello") {
        context => context.response.write("hello cangjie.")
    }

    host.run()
    return 0
}

4. 构建与运行 ​

bash
cjpm update   # 拉取依赖
cjpm build    # 编译
cjpm run      # 启动服务

打开浏览器访问 http://127.0.0.1:5000/hello，页面显示 hello cangjie. 即表示运行成功。