构建独立Vue组件npm库：如何嵌入全局SCSS变量？

我之前也碰到过一模一样的场景——要做一个能按需导入的Vue组件库，既要保留本地开发环境的便捷性，又得让每个组件脱离全局样式文件独立工作。下面分步骤给你两种可行方案，按需选就行：

第一步：先搞定开发环境的全局变量注入 #

不管最终生产构建用哪种方案，先确保npm run serve能正常用全局SCSS变量：

1. 先在项目里建个全局变量文件，比如src/styles/variables.scss，把所有变量放这儿：

$primary-color: #42b983;
$border-radius: 4px;
$font-size-base: 14px;

2. 在vue.config.js里配置sass-loader，让所有组件的<style lang="scss">自动导入这个文件，不用每个组件手动写@import：

module.exports = {
  css: {
    loaderOptions: {
      sass: {
        // 注意：如果你的sass-loader是v8及以下版本，把additionalData换成prependData
        additionalData: `@import "@/styles/variables.scss";`
      }
    }
  }
}

这样开发时所有组件都能直接用这些变量，本地启动完全没问题。

方案一：把SCSS变量编译成静态CSS值（组件完全独立） #

这个方案适合不需要用户定制样式的场景，构建后每个组件的CSS里都是直接的属性值，没有任何变量依赖：

配置组件库打包 #

要让用户能通过import { Button } from "@user/design-system"导入，得调整vue.config.js的构建输出，把项目打包成库的形式：

module.exports = {
  // 保留上面的css配置
  css: {
    loaderOptions: {
      sass: {
        additionalData: `@import "@/styles/variables.scss";`
      }
    }
  },
  configureWebpack: {
    output: {
      library: 'DesignSystem', // 库的名称
      libraryTarget: 'umd', // 支持多种导入方式（ES模块、CommonJS等）
      umdNamedDefine: true
    },
    externals: {
      vue: 'vue' // 不把Vue打包进组件库，让用户自己安装Vue依赖
    }
  },
  chainWebpack: config => {
    // 要支持按需导入，就得把每个组件单独打包
    config.entryPoints.clear()
    // 给每个组件写一个入口文件（比如Button的入口）
    config.entry('button').add('./src/components/Button/index.js')
    // 其他组件同理，比如Input、Card
    // config.entry('input').add('./src/components/Input/index.js')
  }
}

组件入口文件示例 #

比如src/components/Button/index.js得这么写，方便用户按需导入：

import Button from './Button.vue'

Button.install = function(Vue) {
  Vue.component(Button.name, Button)
}

export default Button

配置package.json #

最后在package.json里设置入口和发布文件：

{
  "name": "@user/design-system",
  "main": "dist/design-system.umd.js",
  "module": "dist/design-system.esm.js",
  "files": [
    "dist",
    "src/components"
  ],
  "scripts": {
    "serve": "vue-cli-service serve",
    "build": "vue-cli-service build --target lib --name design-system src/index.js"
  }
}

这里的src/index.js是组件库的总入口，导出所有组件：

import Button from './components/Button'
import Input from './components/Input'

const components = [Button, Input]

const install = function(Vue) {
  components.forEach(component => {
    Vue.component(component.name, component)
  })
}

export { Button, Input }
export default { install }

执行npm run build后，每个组件的CSS都会被编译成静态值，用户导入后直接用，完全不需要你的全局SCSS文件。

方案二：把SCSS变量转成组件内的CSS变量（支持用户定制） #

如果希望用户能通过修改CSS变量来定制组件样式，就用这个方案，把全局SCSS变量映射成CSS变量，嵌入每个组件：

1. 修改src/styles/variables.scss，增加CSS变量的定义（加个前缀避免和用户项目冲突）：

// 原SCSS变量
$primary-color: #42b983;
$border-radius: 4px;

// 映射到CSS变量
:root {
  --ds-primary-color: #{$primary-color};
  --ds-border-radius: #{$border-radius};
}

2. 组件里的SCSS代码改用CSS变量：

.button {
  background-color: var(--ds-primary-color);
  border-radius: var(--ds-border-radius);
}

3. 开发和构建的配置和方案一完全一致，只是组件样式用了CSS变量。构建后每个组件的<style>都会包含这些CSS变量的定义，用户可以通过覆盖:root的变量来定制样式：

/* 用户项目的全局样式 */
:root {
  --ds-primary-color: #ff5722;
}

测试验证 #

构建完成后，你可以在本地新建一个Vue项目，用npm link把组件库链接过去，然后导入Button组件测试：

import { Button } from "@user/design-system"

export default {
  components: { Button }
}

看看组件样式是否正常，有没有依赖你的全局SCSS文件，这样就能确认是否成功了。

内容的提问来源于stack exchange，提问作者supersize