StarRiver-UI

Appearance

安装与接入 ​

本组件库不发布 npm，通过 git 仓库分发。所以直接 pnpm add @starriver/ui 会 404 —— 必须先获取仓库，再接入项目。

下面三步：获取 → 装 less → 按 Vue 3 / Nuxt 4 二选一。

第一步：获取组件库 ​

方式 A：从 git 安装（推荐） ​

不用手动 clone，包管理器直接拉取并放进 node_modules：

bash
pnpm add -D @starriver/ui@git+https://gitee.com/ximengsr/starriver-ui.git#v0.1.0

三个要点：

1. #v0.1.0 是 tag，生产项目务必锁上。

省略不写会跟随默认分支的最新提交——组件库一有新提交，你的项目下次构建就可能发生变化， 而且是自己没改过任何代码的情况下。想永远跟最新才写 #main。

2. 装成 -D（devDependency），不是 dependencies。

组件库以源码形式分发，在构建期被编译进你的产物，运行时不再需要它。 装进 dependencies 只会让部署包里多带一份用不上的源码。

3. Gitee / 自建 Git 必须写完整地址。

github:user/repo 这种简写是 GitHub 专用的，在 Gitee 上不会生效：

bash
# HTTPS（公开仓库）
pnpm add -D @starriver/ui@git+https://gitee.com/ximengsr/starriver-ui.git#v0.1.0

# SSH（私有仓库）
pnpm add -D @starriver/ui@git+ssh://git@gitee.com/ximengsr/starriver-ui.git#v0.1.0

方式 B：clone 到本地（需要改组件库时才用） ​

只有要同时修改组件库本身时才选这种方式。放成同级目录：

bash
cd <你的项目上级目录>
git clone https://gitee.com/ximengsr/starriver-ui.git

再用 file: 引用：

bash
pnpm add -D @starriver/ui@file:../StarRiver-UI

代价是必须额外配置 Vite 的文件访问白名单（见下面「开发态联调的两个必配项」）， 因为组件库此时位于项目上级目录。方式 A 没有这个问题。

装完确认 ​

bash
ls node_modules/@starriver/ui/index.ts

能看到文件就说明获取成功。这一步值得做——包名解析失败时， 错误往往出现在很久之后的某个组件导入上，而不是安装命令本身。

第二步：宿主需自行安装 less ​

组件库以源码形式分发，<style lang="less"> 由宿主项目的构建器编译，因此宿主需要 less：

bash
pnpm add -D less

为什么必须自己装

Nuxt 对本地目录形式的 layer 只做「配置与目录合并」，不会去安装 layer 自身的依赖。 Vue 项目同理——组件库的 package.json 根本不参与你项目的依赖解析。

不需要装 typescript

组件内联 defineProps 类型，不依赖 typescript 包。

Vue 3 项目 ​

1. 注册组件 ​

三种方式，按体积与省事程度取舍。

（1）按需引入 —— 可 tree-shaking，体积最小：

vue
<script setup>
import { SrButton } from '@starriver/ui'
</script>

<template>
  <SrButton variant="primary">主要按钮</SrButton>
</template>

（2）全局注册 —— 省去逐个 import，但所有组件都会进产物：

ts
// src/main.ts
import { createApp } from 'vue'
import StarRiverUI from '@starriver/ui/app/plugin'
import '@starriver/ui/styles/index.less'
import App from './App.vue'

createApp(App).use(StarRiverUI).mount('#app')

之后模板中可直接使用全部组件，无需 import。

（3）自动导入 —— 兼顾省事与体积，推荐：

bash
pnpm add -D unplugin-vue-components
ts
// vite.config.ts
import Components from 'unplugin-vue-components/vite'

export default defineConfig({
  plugins: [
    vue(),
    Components({
      dirs: ['node_modules/@starriver/ui/app/components'],
      dts: 'src/components.d.ts'
    })
  ]
})

2. 引入样式 ​

样式由宿主项目编译，所以用 .less 路径引入：

ts
// src/main.ts
import '@starriver/ui/styles/index.less'

3. 开发态联调的两个必配项 ​

用方式 A（git 安装）时这两项都不用配

它们只在使用 file: / pnpm link 让组件库位于项目上级目录时才需要。

（1）排除依赖预构建

Vite 的依赖预构建走 esbuild，处理不了 .vue。组件库发布的是源码，必须排除：

ts
// vite.config.ts
export default defineConfig({
  optimizeDeps: {
    exclude: ['@starriver/ui']
  }
})

（2）文件访问白名单

用 file: 或 pnpm link 联调时，组件库位于项目上级目录。Vite 会把 node_modules 里的软链解析为真实路径再做访问校验，而默认白名单只有项目根目录，于是报：

The request id "..." is outside of Vite serving allow list

表现为组件能加载，但样式 403、页面失去颜色——很容易误判成「样式没引入」。需显式放行：

ts
// vite.config.ts
import { fileURLToPath } from 'node:url'

export default defineConfig({
  server: {
    fs: {
      allow: [
        fileURLToPath(new URL('.', import.meta.url)),
        fileURLToPath(new URL('..', import.meta.url)) // 组件库所在目录
      ]
    }
  }
})

通过 git 依赖安装时不会有这个问题

包位于项目内的 .pnpm 目录，路径在项目根之下，无需配置白名单。

Nuxt 4 项目 ​

组件库同时是一个 Nuxt layer。用方式 A 或 B 获取后，只需一行：

ts
// nuxt.config.ts
export default defineNuxtConfig({
  extends: ['@starriver/ui']
})

组件、composables、样式全部自动继承，无需任何 import：

vue
<template>
  <SrButton variant="primary">主要按钮</SrButton>
</template>

命令式 API 同样可用，因为它们的实现位于 layer 的 app/utils/ 目录，会被 Nuxt 自动导入：

ts
toast.success('保存成功')
const ok = await srConfirm({ title: '删除确认', type: 'danger' })

样式分层 ​

样式分两层导出，按需选择：

入口内容适用
@starriver/ui/styles/index.less完整样式（含页面背景渐变、滚动条）默认使用
@starriver/ui/styles/core.less仅组件必需（tokens + mixins + reset + 组件样式）宿主已有自己的背景与 reset

目录红线

组件库仓库内不得出现 pages/、layouts/、middleware/、server/ 目录——作为 Nuxt layer 时，这些目录会被所有引用它的项目继承。

常见问题 ​

直接 pnpm add @starriver/ui 报 404 ​

正常的，它不在 npm 上。按上面的方式 A 或 B 获取。

组件能显示但没有样式、页面失去颜色 ​

file: 联调时几乎都是白名单没配（本节第 3 条的（2））。 样式请求被 Vite 以 403 拦下，而组件 JS 已经加载了——所以看起来是「组件在、样式没在」。

提示 Failed to resolve component: SrXxx ​

组件没注册上。检查用的是哪种方式：全局注册要确认 main.ts 里 .use(StarRiverUI) 已执行， 自动导入要确认 dirs 指向 node_modules/@starriver/ui/app/components。

更新到新版本 ​

bash
# 锁 tag 时：改 package.json 里的 tag 后重新安装
pnpm update @starriver/ui

# 跟随分支时：lockfile 锁定的是 commit，需显式拉取
pnpm update @starriver/ui --latest

下一步 ​

自用组件库 · 源码分发 · 不发布 npm

StarRiver-UI