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

## 问题描述

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

## 问题现象

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

## 根本原因

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

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

```javascript
// 原配置 - 问题配置
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 插件：

```javascript
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 版本

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

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

```bash
npm install sass@1.32.13 --save
```

## 修复后的依赖版本

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

## 验证方法

1. 构建项目：
```bash
npm run build:h5
```

2. 检查构建后的 JS 文件中 rpx 是否被转换：
```bash
# 应该看到 %?90?% 这样的占位符，而不是 90rpx
grep -oE "height:%\?[0-9]+\?%" dist/build/h5/static/js/pages-login-login.*.js
```

3. 启动开发服务器验证样式：
```bash
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

## 相关命令

```bash
# 安装 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`