Sailoud Micro Program (SMP)

Sailoud 小程序框架 CLI 工具，用于 Sailoud 小程序的开发、构建与部署。

Sailoud Micro Program framework CLI tool for developing, building, and deploying Sailoud micro programs.

安装 / Installation

npm install -g @sailoud/smp

命令详解 / Command Details

smp init [project-name]

初始化一个新的 Sailoud 小程序项目。CLI 会自动下载官方模板，解压后让你选择模板类型，然后生成项目目录。

Initialize a new Sailoud micro program project. The CLI downloads the official template, lets you choose a template type, and scaffolds the project directory.

# 使用默认项目名 "smp-project" / Use default project name "smp-project"
smp init

# 指定项目名 / Specify a project name
smp init my-app

smp dev

启动本地开发服务器。会编译小程序并启动一个 WebSocket 服务，将你的 Sailoud App 连接到开发服务器后即可实时预览和热重载。

Start the local development server. It compiles the micro program and starts a WebSocket server. Connect your Sailoud App to the server for live preview and hot reload.

参数 / Options:

| 参数 Option | 类型 Type | 默认值 Default | 说明 Description | |---|---|---|---| | --port | string | 6589 | 开发服务器端口 / Development server port |

# 使用默认端口 / Use default port
smp dev

# 指定端口 / Specify a custom port
smp dev --port=8080

启动成功后，终端会输出可用的局域网地址，使用 Sailoud App 连接即可。

After startup, the terminal will display available LAN addresses. Use the Sailoud App to connect.

smp build

构建小程序的生产版本。编译完成后自动打包为 dist/build/app.wgt 文件。

Build the production version of the micro program. After compilation, it is automatically packaged into dist/build/app.wgt.

smp build

smp deploy

将小程序部署到 Sailoud 开发者平台。默认会先执行构建，再上传 .wgt 包。需要先登录或提供 Access Key。

Deploy the micro program to the Sailoud developer platform. By default, it builds first, then uploads the .wgt package. Requires prior login or an Access Key.

参数 / Options:

| 参数 Option | 类型 Type | 默认值 Default | 说明 Description | |---|---|---|---| | --token | string | - | Access Key，跳过登录认证 / Access Key, skip login auth | | --build | boolean | true | 部署前是否构建 / Whether to build before deploying | | --api_origin | string | - | 自定义 API 地址 / Custom API origin URL |

# 先登录，然后部署（自动构建）/ Login first, then deploy (auto build)
smp deploy

# 跳过构建，仅部署 / Skip build, deploy only
smp deploy --build=false

# 使用 Access Key 部署 / Deploy with an Access Key
smp deploy --token=YOUR_ACCESS_KEY

# 使用自定义 API 地址 / Use a custom API origin
smp deploy --api_origin=https://custom-api.example.com

包体积上限为 30MB。部署前请确保 src/manifest.json 中已正确配置 appid 和 versionCode。

The package size limit is 30MB. Make sure appid and versionCode are properly configured in src/manifest.json before deploying.

smp login

登录 Sailoud 开发者平台。执行后会自动打开浏览器跳转到 SSO 登录页面，完成登录后凭据会保存到本地。

Log in to the Sailoud developer platform. A browser window will open automatically for SSO authentication. Credentials are saved locally upon success.

smp login

smp logout

退出当前登录状态，删除本地保存的凭据。

Log out and remove locally stored credentials.

smp logout

smp prepare

安装当前项目所需的 peer 依赖。CLI 会自动识别你使用的包管理器（npm / yarn / pnpm / bun）并执行安装。

Install the required peer dependencies for the current project. The CLI automatically detects your package manager (npm / yarn / pnpm / bun) and runs the install command.

smp prepare

smp update

将 @sailoud/smp 及其所有 peer 依赖更新到最新版本。

Update @sailoud/smp and all its peer dependencies to the latest version.

smp update

smp upgrade

升级全局安装的 @sailoud/smp CLI 工具到最新版本。如果已经是最新版则不做任何操作。

Upgrade the globally installed @sailoud/smp CLI to the latest version. No action is taken if already up to date.

smp upgrade

smp version

输出当前 CLI 的版本号。

Print the current CLI version.

smp version

smp mcp

启动 SMP 文档 MCP（Model Context Protocol）服务器，提供 API 文档的搜索与查询能力，供 AI 编程助手等工具使用。

Start the SMP documentation MCP (Model Context Protocol) server, providing API doc search and query capabilities for AI coding assistants and other tools.

参数 / Options:

| 参数 Option | 类型 Type | 默认值 Default | 说明 Description | |---|---|---|---| | --docs | string | 自动检测 / Auto-detected | smp.api.json 文件路径 / Path to smp.api.json |

# 自动查找文档文件 / Auto-detect docs path
smp mcp

# 指定文档路径 / Specify docs path
smp mcp --docs=./docs/public/json/smp.api.json

MCP 服务提供以下工具 / The MCP server provides the following tools:

• smp_search_docs — 按关键词搜索 API 文档 / Search API docs by keyword
• smp_get_doc — 获取指定 API 的详细文档 / Get detailed doc for a specific API
• smp_list_capabilities — 列出所有可用的 API 和类型定义 / List all available APIs and type definitions

项目结构 / Project Structure

通过 smp init 创建的项目基于 Vue 3 + Vite 技术栈，目录结构如下：

Projects created via smp init are based on the Vue 3 + Vite tech stack. The directory structure is as follows:

my-app/
├── .cursor/mcp.json          # Cursor IDE MCP 配置 / Cursor IDE MCP config
├── .vscode/mcp.json           # VS Code MCP 配置 / VS Code MCP config
├── .mcp.json                  # 根目录 MCP 配置 / Root MCP config
├── src/
│   ├── pages/                 # 页面目录 / Pages directory
│   │   └── index/
│   │       └── index.vue      # 首页 / Home page
│   ├── static/                # 静态资源 / Static assets
│   │   └── logo.png
│   ├── App.vue                # 应用入口组件 / App entry component
│   ├── main.ts                # 应用入口文件 / App entry file
│   ├── manifest.json          # 应用配置 / App configuration
│   ├── pages.json             # 页面路由配置 / Page routing config
│   ├── uni.scss               # 全局样式变量 / Global style variables
│   ├── env.d.ts               # Vite 环境类型声明 / Vite env type declarations
│   └── shime-uni.d.ts         # SMP 类型声明 / SMP type declarations
├── .gitignore
├── index.html                 # H5 入口 HTML / H5 entry HTML
├── package.json
├── shims-uni.d.ts             # SMP 生命周期类型声明 / SMP lifecycle type declarations
├── tsconfig.json              # TypeScript 配置 / TypeScript configuration
└── vite.config.ts             # Vite 构建配置 / Vite build configuration

文件说明 / File Descriptions

vite.config.ts

Vite 构建配置文件。通过 @sailoud/smp/vite 引入 SMP 插件，该插件会自动集成编译所需的 Vite 插件链。

Vite build configuration. The SMP plugin imported from @sailoud/smp/vite automatically integrates the required compilation plugin chain.

import { defineConfig } from "vite";
import { smp } from "@sailoud/smp/vite";

export default defineConfig({
  plugins: [smp()],
});

src/manifest.json

SMP 应用配置文件（支持 JSON5 语法），是整个小程序最重要的配置文件。包含应用的基本信息及各平台的特定配置。

The SMP application configuration file (supports JSON5 syntax), the most important config file for the micro program. Contains basic app info and platform-specific settings.

关键字段 / Key fields:

| 字段 Field | 说明 Description | |---|---| | name | 应用名称 / Application name | | appid | 必填，Sailoud 小程序 ID，部署时使用 / Required, Sailoud micro program ID, used for deployment | | versionName | 版本名称，如 "1.0.0" / Version name, e.g. "1.0.0" | | versionCode | 必填，版本号（整数字符串），每次部署需递增 / Required, version code (integer string), must increment on each deployment | | app-plus | App 平台特有配置（启动屏、模块、权限等）/ App platform settings (splash screen, modules, permissions, etc.) | | mp-weixin | 微信小程序配置 / WeChat mini program settings |

src/pages.json

页面路由与窗口表现配置文件。定义小程序的所有页面路径及导航栏样式。pages 数组的第一项即为应用启动页。

Page routing and window appearance configuration. Defines all page paths and navigation bar styles. The first item in the pages array is the app's launch page.

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "smp"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "smp",
    "navigationBarBackgroundColor": "#F8F8F8",
    "backgroundColor": "#F8F8F8"
  }
}

src/App.vue

应用入口组件，用于处理应用级别的生命周期。App.vue 不渲染页面 UI，仅用于监听应用的启动、显示、隐藏等全局事件。

The app entry component for handling application-level lifecycle events. App.vue does not render page UI — it only listens for global events like app launch, show, and hide.

可用的生命周期钩子 / Available lifecycle hooks:

| 钩子 Hook | 触发时机 / When triggered | |---|---| | onLaunch | 应用初始化完成时触发（全局仅一次）/ When app initialization completes (once globally) | | onShow | 应用从后台进入前台时触发 / When app enters foreground from background | | onHide | 应用从前台进入后台时触发 / When app enters background from foreground |

@sailoud/smp 导出的 onLaunch 会将宿主传入的 referrerInfo.extraData.data 解包为 referrerInfo.extraData。

The onLaunch exported by @sailoud/smp unwraps host-provided referrerInfo.extraData.data as referrerInfo.extraData.

src/main.ts

应用入口文件。使用 Vue 3 的 createSSRApp 创建应用实例。可在此文件中注册全局组件、插件、状态管理等。

The app entry file. Creates the app instance using Vue 3's createSSRApp. You can register global components, plugins, state management, etc. here.

import { createSSRApp } from "vue";
import App from "./App.vue";

export function createApp() {
  const app = createSSRApp(App);
  return { app };
}

src/pages/

页面目录。每个页面对应一个子目录，包含一个 .vue 文件。页面路径需在 pages.json 中注册后才能访问。

Pages directory. Each page corresponds to a subdirectory containing a .vue file. Page paths must be registered in pages.json to be accessible.

例如 / For example: src/pages/index/index.vue 对应路由 / corresponds to route pages/index/index。

src/static/

静态资源目录。存放图片、字体等不需要编译处理的静态文件。可在代码中通过绝对路径 /static/xxx 引用。

Static assets directory. Stores images, fonts, and other static files that don't need compilation. Reference in code via absolute path /static/xxx.

src/uni.scss

全局 SCSS 样式变量文件。在此文件中定义的变量可在项目的任何 .vue 文件中直接使用，无需手动 @import。预置了常用的主题变量（颜色、字号、间距、圆角等）。

Global SCSS style variables file. Variables defined here are available in any .vue file without manual @import. Pre-configured with commonly used theme variables (colors, font sizes, spacing, border radius, etc.).

index.html

H5 平台的入口 HTML 文件。SMP 编译时会自动注入预加载链接和应用上下文，一般无需修改。

The entry HTML file for the H5 platform. SMP automatically injects preload links and app context during compilation. Typically no modifications are needed.

tsconfig.json

TypeScript 配置文件。继承自 @vue/tsconfig，已配置 @/* 路径别名（指向 src/），并引入了 @dcloudio/types 和 @sailoud/smp/types 类型声明。

TypeScript configuration. Extends @vue/tsconfig, with @/* path alias configured (pointing to src/), and includes @dcloudio/types and @sailoud/smp/types type declarations.

shims-uni.d.ts / src/shime-uni.d.ts / src/env.d.ts

TypeScript 类型声明文件，为 SMP 生命周期钩子、.vue 文件模块以及 Vite 环境变量提供类型支持。

TypeScript declaration files providing type support for SMP lifecycle hooks, .vue file modules, and Vite environment variables.

.mcp.json

MCP 配置文件，为 AI 编程助手预配置了 SMP 文档 MCP 服务器，使其能够查询 SMP API 文档。

MCP configuration file, pre-configured with the SMP docs MCP server for AI coding assistants to query SMP API documentation.

{
  "mcpServers": {
    "smp-docs": {
      "command": "smp",
      "args": ["mcp"]
    }
  }
}