问题：如何在UniApp中全局引入uni.scss并避免编译错误？

Question

在使用 UniApp 开发跨平台应用时，如何正确全局引入 uni.scss 样式文件并避免编译错误是一个常见问题。许多开发者在全局样式中直接引入 uni.scss 后，遇到如“@import can only import CSS or SCSS files”或重复引入导致的编译冲突。主要原因在于不同平台对 SCSS 的处理方式不一致，或引入路径不规范。解决该问题的关键在于使用正确的引入方式和路径配置。通常建议在项目的 main.scss 或全局样式入口中，通过相对路径引入 uni.scss，并确保项目结构和编译配置支持 SCSS 解析。此外，使用 HBuilderX 或配置 webpack、vite 等构建工具时，需确认 sass/scss 插件已安装并正确配置，以避免编译异常。

Answer 1

一、问题背景与常见表现

在使用 UniApp 开发跨平台应用时，开发者常常希望在全局样式中引入 UniApp 提供的 uni.scss 文件，以便统一使用其内置的 SCSS 变量和工具类。然而，在实际操作中，很多开发者会遇到如下编译错误：

• @import can only import CSS or SCSS files
• File to import not found or unreadable
• Duplicate mixins or variables

这些问题通常源于引入路径不规范、SCSS 编译器未正确配置或不同平台对 SCSS 的处理机制不同。

二、深入分析：不同平台对 SCSS 的处理机制

UniApp 作为跨平台框架，底层依赖于不同平台的编译器（如 H5、小程序、App）。不同平台对 SCSS 的支持存在差异：

平台	SCSS 支持情况	常见问题
H5	完全支持	路径错误导致引入失败
微信小程序	有限支持	变量重复定义
App（5+ App）	支持需配置	未安装 sass 插件

三、解决方案与最佳实践

为避免上述问题，建议采用以下步骤进行全局引入：

1. 创建全局 SCSS 入口文件（如 main.scss）
2. 使用相对路径引入 uni.scss
3. 确保项目中安装并配置了 sass 或 node-sass 插件
4. 在 pages.json 中配置样式入口

示例代码如下：

@import "./static/scss/uni.scss";

在 main.js 中引入该文件：

import './main.scss'

四、构建工具配置建议

若使用 HBuilderX 或自定义构建工具（如 webpack、vite），请确保已正确安装并配置 SCSS 插件。例如，在 vite 项目中，应安装：

npm install -D sass

并在 vite.config.js 中添加：

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@import "./src/static/scss/uni.scss";`
      }
    }
  }
})

五、流程图：全局引入 uni.scss 的标准流程

graph TD
    A[创建 main.scss 全局样式入口] --> B[使用相对路径引入 uni.scss]
    B --> C[安装 sass/scss 插件]
    C --> D[配置构建工具支持 SCSS]
    D --> E[在 main.js 中导入 main.scss]
    E --> F[运行项目，验证样式是否生效]

六、进阶技巧与注意事项

为了进一步避免重复引入或变量冲突，建议：

• 使用 @use 替代 @import（适用于 Sass 1.23+）
• 使用命名空间管理变量
• 在引入前判断是否已定义变量，避免冲突

@if not variable-exists("uni-color-primary") {
  @import "./uni.scss";
}