736aa08fba
详细记录了问题原因、解决方案和技术细节 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
167 lines
3.7 KiB
Markdown
167 lines
3.7 KiB
Markdown
# 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`
|