martial-admin-mini/doc/Linux命令行编译样式问题修复记录.md

Linux/Mac 命令行编译样式异常问题修复记录

问题描述

在 Windows 上使用 HBuilderX 运行项目时样式正常，但在 Linux/Mac 上使用 npm run dev:h5 命令行编译时，页面样式完全异常，组件的 scoped 样式没有生效。

问题现象

• 页面布局错乱
• rpx 单位没有被转换为 px
• 组件的 scoped 样式没有被正确打包

根本原因

1. postcss.config.js 配置覆盖问题

项目中自定义的 postcss.config.js 文件覆盖了 uni-app 的默认 postcss 配置：

// 原配置 - 问题配置
const autoprefixer = require('autoprefixer')

module.exports = {
  plugins: [
    autoprefixer()
  ]
}

这个配置没有包含 uni-app 的 postcss 插件，导致：

• rpx 单位没有被转换为 %?数值?% 占位符格式
• uni-app 运行时无法在浏览器中将占位符转换为实际的 px 值

2. HBuilderX vs 命令行编译的区别

特性	HBuilderX	命令行 (npm run dev:h5)
编译器	内置优化版编译器	依赖 node_modules
rpx 处理	自动转换	需要 postcss 插件
样式处理	完善的内置处理	依赖配置文件
版本兼容	内部统一管理	可能存在版本冲突

3. PostCSS 版本兼容问题

• 项目使用 postcss-loader@3.0.0（旧版）
• 但 postcss 被升级到了 8.x 版本
• postcss-loader 3.x 与 postcss 8 不兼容

解决方案

1. 修改 postcss.config.js

添加 uni-app 的 postcss 插件：

const autoprefixer = require('autoprefixer')

// 引入 uni-app 的 postcss 插件来处理 rpx 转换
const uniappPlugin = require('@dcloudio/vue-cli-plugin-uni/packages/postcss')

module.exports = {
  plugins: [
    uniappPlugin,
    autoprefixer
  ]
}

2. 降级 postcss 版本

npm install postcss@7 --save --legacy-peer-deps

3. 降级 sass 版本（可选，提高兼容性）

npm install sass@1.32.13 --save

修复后的依赖版本

{
  "dependencies": {
    "postcss": "^7.0.39",
    "postcss-loader": "^3.0.0",
    "sass": "^1.32.13"
  }
}

验证方法

1. 构建项目：

npm run build:h5

2. 检查构建后的 JS 文件中 rpx 是否被转换：

# 应该看到 %?90?% 这样的占位符，而不是 90rpx
grep -oE "height:%\?[0-9]+\?%" dist/build/h5/static/js/pages-login-login.*.js

3. 启动开发服务器验证样式：

npm run dev:h5
# 访问 http://localhost:8080 查看样式

技术细节

uni-app 的 rpx 转换流程

1. 编译时：postcss 插件将 90rpx 转换为 %?90?% 占位符
2. 运行时：uni-app 的 Vue 运行时根据屏幕宽度将占位符转换为实际 px 值
3. 计算公式：px = rpx * (屏幕宽度 / 750)

相关文件

• /postcss.config.js - PostCSS 配置
• /node_modules/@dcloudio/vue-cli-plugin-uni/packages/postcss/index.js - uni-app postcss 插件
• /node_modules/@dcloudio/vue-cli-plugin-uni/packages/h5-vue/dist/vue.runtime.esm.js - 运行时 rpx 转换

注意事项

1. 不要随意升级 postcss 版本：postcss-loader 3.x 只兼容 postcss 7.x
2. 保留 uni-app postcss 插件：这是 rpx 转换的关键
3. Node.js 版本建议：使用 Node 16.x 以获得最佳兼容性

环境要求

• Node.js: 16.x (推荐 16.20.2)
• npm: 8.x
• postcss: 7.x
• postcss-loader: 3.x

相关命令

# 安装 nvm（如果没有）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 切换到 Node 16
nvm install 16
nvm use 16

# 重新安装依赖
rm -rf node_modules package-lock.json
npm install

# 开发模式
npm run dev:h5

# 生产构建
npm run build:h5

修复日期

2024-12-17

修复分支

devops