docs: 添加 Linux 命令行编译样式问题修复记录

详细记录了问题原因、解决方案和技术细节

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

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

@@ -0,0 +1,166 @@
+# 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`