gimc-fronted-components

基于 Vue 3 + Element Plus 的业务组件库，提供一系列开箱即用的通用 UI 组件。

技术栈

• Vue 3.4+ (Composition API)
• TypeScript 5.6+
• Vite 5.4+
• Element Plus 2.8+
• SCSS

安装

npm install gimc-fronted-components
# 或
yarn add gimc-fronted-components

前置依赖

项目依赖以下 peerDependencies，请确保已安装：

npm install vue@^3.4.0 element-plus@^2.8.0

使用

全局注册

import { createApp } from 'vue'
import GimcUI from 'gimc-fronted-components'
import 'gimc-fronted-components/dist/style.css'
import App from './App.vue'

const app = createApp(App)
app.use(GimcUI)
app.mount('#app')

按需导入

import { GimcUpload, GimcDatePicker } from 'gimc-fronted-components'
import 'gimc-fronted-components/dist/style.css'

避免循环依赖（chunkSplitPlugin 配置）

⚠️ 重要配置提示 如果你的项目同时使用了 gimc-fronted-components 和 element-plus，必须在 vite.config.ts 中配置 chunkSplitPlugin.customSplitting，将两者打包在一起以避免循环依赖问题：

// vite.config.ts
import { chunkSplitPlugin } from 'vite-plugin-chunk-split'

export default defineConfig({
  plugins: [
    chunkSplitPlugin({
      customSplitting: {
        // 将 gimc-fronted-components 与 element-plus 打包在一起，避免循环依赖
        'element-vendor': [/node_modules\/(element-plus|gimc-fronted-components)/],
        // 使用负向前瞻排除已单独拆分的包
        'vendor': [/node_modules\/(?!(element-plus|gimc-fronted-components))/],
      }
    })
  ]
})

组件列表

| 组件 | 说明 | | ------------------ | ---------------- | | GimcCommonSearch | 通用搜索组件 | | GimcCommonTabs | 通用标签页组件 | | GimcDatePicker | 日期选择器 | | GimcPopover | 弹出框组件 | | GimcUpload | 文件上传组件 | | GimcSelectMultiple | 多选下拉组件 | | GimcTransfer | 穿梭框组件 | | GimcRemoteSelect | 远程搜索下拉组件 | | GimcSvgIcon | SVG 图标组件 |

开发

# 安装依赖
npm install

# 启动组件开发服务器
npm run dev

# 启动文档站点
npm run docs:dev

# 构建组件库
npm run build

# 构建并监听文件变化（用于实时调试）
npm run build:watch

# 代码检查
npm run eslint
npm run tslint
npm run stylelint

在其他项目中调试组件库

当你需要在其他项目中实时调试组件库时，可以使用以下方法：

方法 1：npm link（调试生产）

步骤 1：在组件库项目中创建链接

# 构建组件库
npm run build

# 创建全局链接
npm link

步骤 2：在使用项目中链接组件库

# 进入使用项目目录
cd /path/to/your-project

# 链接组件库
npm link gimc-fronted-components --legacy-peer-deps

步骤 3：启动实时更新（可选）

在组件库项目中启动 watch 模式，修改代码后自动重新构建：

npm run build:watch

然后在使用项目中正常启动开发服务器，修改组件库代码后会自动更新。

取消链接

# 在使用项目中
npm unlink gimc-fronted-components --legacy-peer-deps

# 恢复 npm 包
npm install --force

方法 2：Vite alias（日常开发，最快，无需构建）

在使用项目的 vite.config.ts 中添加别名，直接指向组件库源码,开发完成需要注释或者移除：

import path from 'path'

export default defineConfig({
  resolve: {
    alias: {
      'gimc-fronted-components': path.resolve(__dirname, '../gimc-fronted-comp-docs/src'),
    }
  },
  server: {
    ...,
    fs: {
      allow: [
        path.resolve(__dirname),
        path.resolve(__dirname, '../gimc-fronted-comp-docs')
      ]
    }
  }
})

这样可以直接读取组件库源码，修改后立即生效，无需任何构建步骤。

注意：使用 alias 指向组件库源码时，必须同时配置 server.fs.allow。 需要注释src/main.ts中的这行代码 ‘import 'gimc-fronted-components/dist/style.css'’，结束后还原 原因：Vite 开发服务器出于安全考虑，默认只允许访问项目自身根目录内的文件。alias 将 gimc-fronted-components 指向了组件库的源码目录（位于项目根目录之外），当业务代码引入组件库样式时，Vite 会顺着路径去读取组件库目录下的字体文件（如 iconfont.woff2），此时触发跨目录访问限制并报错。fs.allow 显式将组件库目录加入白名单，Vite 才允许访问其中的资源。

SVG 图标配置

组件库使用 SVG sprite 方式管理图标。如果使用项目配置了 vite-plugin-svg-icons，需要将组件库的图标目录添加到扫描路径：

import { createSvgIconsPlugin } from 'vite-plugin-svg-icons'
import path from 'path'

export default defineConfig({
  plugins: [
    createSvgIconsPlugin({
      iconDirs: [
        path.resolve(process.cwd(), 'src/assets/icons'),
        // 添加组件库图标目录
        path.resolve(__dirname, 'node_modules/gimc-fronted-components/src/assets/icons')
      ],
      symbolId: '[name]',
    })
  ]
})

文档

组件详细用法和 API 请参考 在线文档站点，本地启动：

npm run docs:dev

发布到 npm

发布前准备

1. 确保所有新组件已在 src/index.ts 中导出
2. 更新版本号（每次发布必须递增）

# 编辑 package.json，手动更新 version 字段
# 例如：1.0.2 -> 1.0.3

发布步骤

1. 构建组件库

npm run build

构建完成后会在 dist/ 目录生成以下文件：

• gimc-fronted-components.es.js - ES Module 格式
• gimc-fronted-components.umd.js - UMD 格式
• style.css - 样式文件
• index.d.ts - TypeScript 类型声明

2. 检查 npm 镜像源

发布前必须切换到 npm 官方源：

# 查看当前镜像源
npm config get registry

# 如果不是官方源，切换到官方源
npm config set registry https://registry.npmjs.org/

3. 登录 npm 账号

npm login

按提示输入用户名、密码和邮箱。

4. 发布到 npm

npm publish

如果是首次发布该包名，确保包名未被占用。如果包已存在，确保你是该包的维护者。

5. 验证发布

# 查看包信息
npm info gimc-fronted-components

# 或访问 npm 官网
# https://www.npmjs.com/package/gimc-fronted-components

发布后恢复镜像源

如果之前使用淘宝镜像，可以切换回去：

npm config set registry https://registry.npmmirror.com/

注意事项

• 版本号必须遵循语义化版本规范（Semantic Versioning）
• 每次发布前确保代码已提交到 Git
• 发布后的版本无法删除，只能发布新版本
• 如果发布失败，检查是否有权限或版本号是否重复

Vite 项目中 npm link 不生效

在 Vite 项目里执行下面命令后，如果业务项目里看到的仍然是旧组件代码，通常不是 npm link 本身失败，而是 Vite 仍在使用旧的依赖处理结果：

npm link gimc-fronted-components --legacy-peer-deps

这类情况通常集中在两个原因：

1. Dev Server 没有重启

Vite 会在启动时扫描并处理 node_modules 依赖。如果你是在 npm run dev2 已经运行的过程中再执行 npm link，当前开发服务一般不会自动感知这次链接变更。

处理方式：

# 先停止当前服务
Ctrl + C

# 再重新启动
npm run dev2

2. Vite 依赖预构建缓存没有刷新

Vite 会把依赖预构建结果缓存到 node_modules/.vite。即使已经重启服务，只要缓存仍被命中，Vite 也可能继续使用旧结果，因此链接后的代码看起来没有生效。

处理方式：

# 强制 Vite 重新预构建依赖
npm run dev2 -- --force

也可以手动删除缓存目录后再启动：

rm -rf node_modules/.vite
npm run dev2

结论

在 Vite 项目中，npm link 后组件库没有生效时，优先检查：

1. npm link 是否发生在开发服务启动之后。如果是，先重启 dev server。
2. 是否命中了 Vite 的依赖预构建缓存。如果是，使用 --force 或清理 node_modules/.vite 后再启动。

如果你正在本地联调组件库，建议同时开启组件库的监听构建，例如：

npm run build:watch

这样组件库产物更新后，业务项目更容易拿到最新内容。

License

MIT