运行环境与能力边界
Snake UI 运行在 uni-app Vue 3 环境中。基础组件开箱即用；商城和 CMS 组件可能需要宿主项目提供业务服务。
基础要求
| 项目 | 要求 |
|---|---|
| Vue | Vue 3，包清单声明 >= 3.4.0 |
| uni-app | 包清单声明 >= 3.0.0 |
| 组件格式 | Vue 单文件组件，可处理 SCSS 与 rpx |
| 运行时 | 可使用 uni、uni-app 内置组件和条件编译 |
普通 Vue Web 工程即使能编译 .vue，也不等同于完整的 uni-app 环境。
编辑器与编译
推荐工具链
- 推荐 VSCode + Volar 开发；类型提示与校验体验最佳，详见代码提示。
- HBuilderX 可以编译与预览，但 TypeScript 提示能力弱于 Volar，复杂类型可能不提示。
- 线上项目使用 HBuilderX 稳定版；内测版留给尝鲜环境，避免莫名其妙的编译问题。
SCSS 支持
宿主需要处理 SCSS（引入 theme.scss 或 index.scss 时）。HBuilderX 项目请确认已安装「sass/scss 编译」插件；CLI 项目由依赖提供。
编译调试
- 写布局阶段用浏览器快速迭代，但浏览器预览不等于真机表现（rpx 与设备像素比存在差异）。
- 写完一个页面就用小程序模拟器或 App 基座真机验证一次，特别是导航、弹层、滚动与吸顶。
- 修改
pages.json（如 easycom 配置）后需要重新编译；开发服务有缓存时应重启一次。
内置能力
插件安装后会提供：
- Snake UI 基础组件与独立样式。
- 模板和 Options API 中的
$snake。 - 脚本中的
uni.$snake。 - 可从
@puresnake/snake-ui或@puresnake/snake-ui/libs按需导入的工具。
组件库内部和宿主项目不应继续依赖 uni.$u。
按需提供的业务能力
| 配置 | 何时需要 | 缺失时的表现 |
|---|---|---|
request | 将 Snake HTTP 请求委托给宿主实现 | 请求无法使用宿主适配器 |
cache | 商品列表等需要缓存的业务流程 | 不缓存或由对应逻辑报告错误 |
config | 旧版服务地址、外链等业务配置 | 对应能力无法解析配置 |
cms.services | 商品、优惠券、外链的正式接入方式 | 相关组件无法完成业务动作 |
纯展示组件不需要这些配置。CMS 的推荐服务接口见装修编辑器数据对接。
平台差异
| 能力 | H5 | App | 微信小程序 | 支付宝小程序 |
|---|---|---|---|---|
| 基础组件与主题变量 | √ | √ | √ | √ |
uni.navigateToMiniProgram | — | — | 需目标端支持 | 需目标端支持 |
| 任意外链跳转 | window.location | 内置浏览器或 WebView | WebView 承载页 | WebView 承载页 |
| 系统主题监听 | 受浏览器支持影响 | 受系统版本影响 | 受基础库版本影响 | 受基础库版本影响 |
| 页面滚动与节点测量 | 页面上下文 | 页面上下文 | 页面上下文 | 页面上下文 |
styleIsolation、virtualHost 等配置主要影响小程序组件样式和节点结构；页面滚动、吸顶和节点测量组件必须在正确的页面或组件上下文中运行。
验证建议
仓库清单列出的平台表示具备构建目标，不代表所有业务组件都已在所有版本和机型完成验证。发布前至少在实际目标端检查导航、弹层、滚动、主题和业务 API。