# 微信公众号平台限制说明

本文档详细说明微信公众号编辑器的技术限制，以及本工具如何应对这些限制。

---

## 1. 核心技术限制

### 1.1 不支持外部CSS文件

**限制说明**:
- 微信编辑器不允许使用 `<link>` 标签引用外部CSS文件
- 不支持 `<style>` 标签中的CSS规则
- 只支持HTML元素的内联 `style` 属性

**本工具的解决方案**:
```html
<!-- ❌ 微信不支持 -->
<link rel="stylesheet" href="style.css">
<style>
  h1 { color: blue; }
</style>

<!-- ✅ 本工具的输出 -->
<h1 style="color: #7c3aed; font-size: 28px; font-weight: 700;">标题</h1>
```

**实现细节**:
- 使用CSS解析器将所有CSS规则转换为内联样式
- 自动合并多个选择器的样式
- 处理CSS变量（`:root`）并替换为实际值

### 1.2 不支持JavaScript

**限制说明**:
- 完全禁用所有JavaScript代码
- 不支持 `<script>` 标签
- 不支持事件属性（如 `onclick`, `onload` 等）

**影响**:
- 无法实现交互功能（如折叠、切换、动画等）
- 代码语法高亮必须使用静态CSS实现

**本工具的解决方案**:
- 使用纯CSS实现代码语法高亮
- 使用静态HTML结构，无需JavaScript
- 使用CSS伪元素实现装饰效果

### 1.3 有限的CSS属性支持

**不支持的CSS属性**:
```css
/* ❌ 微信不支持的属性 */
position: fixed;         /* 固定定位 */
position: sticky;        /* 粘性定位 */
transform: rotate();     /* 3D变换 */
animation: ...;          /* CSS动画 */
@keyframes ...;          /* 关键帧动画 */
filter: blur();          /* 滤镜效果 */
backdrop-filter: ...;    /* 背景滤镜 */
```

**支持的CSS属性**:
```css
/* ✅ 微信支持的常用属性 */
color, background, background-color
font-size, font-weight, font-family
padding, margin, border
width, height, max-width, max-height
text-align, line-height, letter-spacing
border-radius, box-shadow
display, flex, justify-content, align-items
```

**本工具的策略**:
- 只使用微信支持的CSS属性
- 避免使用动画、变换等高级特性
- 使用基础CSS实现专业视觉效果

### 1.4 图片处理限制

**限制说明**:
- 不支持本地图片路径（如 `file:///` 或相对路径）
- 图片必须上传到微信服务器或使用外部图床
- 图片大小建议 < 5MB
- 支持的格式：JPG、PNG、GIF

**本工具的处理**:
```html
<!-- ❌ 微信不支持 -->
<img src="./images/cover.png">
<img src="file:///C:/Users/user/image.png">

<!-- ✅ 需要用户手动处理 -->
<img src="https://imagebed.com/cover.png">
<!-- 或在微信编辑器中重新上传 -->
```

**用户操作流程**:
1. 复制HTML到微信编辑器
2. 在编辑器中删除无法显示的图片
3. 点击"插入图片"上传本地图片
4. 或使用图床链接替换 `src` 属性

### 1.5 代码块限制

**限制说明**:
- 不支持JavaScript语法高亮库（如highlight.js）
- 代码块中的换行和缩进容易丢失
- 不支持代码行号的动态生成

**本工具的解决方案**:
```html
<!-- 使用<pre>标签保留格式 -->
<pre style="background: #282c34; color: #abb2bf; padding: 16px; ...">
<code style="font-family: 'Consolas', monospace; font-size: 14px;">
def hello_world():
    print("Hello, World!")
</code>
</pre>
```

- 使用 `<pre>` 和 `<code>` 保留代码格式
- 使用内联样式实现语法高亮
- 使用 `white-space: pre` 保留换行和缩进

---

## 2. 排版限制

### 2.1 最大宽度限制

**限制说明**:
- 微信公众号文章最大宽度：约 750px（移动端）
- 建议内容宽度：720px - 740px

**本工具的处理**:
```css
body {
  max-width: 720px;
  margin: 0 auto;
}
```

### 2.2 字体限制

**限制说明**:
- 微信不支持 `@font-face` 自定义字体
- 只能使用系统字体

**本工具使用的字体栈**:
```css
font-family: -apple-system, BlinkMacSystemFont,
  "Segoe UI", Roboto, "Helvetica Neue", Arial,
  "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei",
  sans-serif;
```

- iOS/macOS: `-apple-system`, `PingFang SC`
- Android: `Roboto`
- Windows: `Microsoft YaHei`
- 通用备选: `Arial`, `sans-serif`

### 2.3 表格限制

**限制说明**:
- 表格在移动端容易超出屏幕
- 复杂表格（合并单元格）支持有限

**本工具的处理**:
```css
table {
  width: 100%;
  overflow-x: auto;
  display: block;
}
```

- 表格宽度设为 100%
- 使用 `overflow-x: auto` 支持横向滚动
- 建议表格列数 ≤ 4 列

---

## 3. 内容限制

### 3.1 文章长度限制

**官方限制**:
- 单篇文章最多 20,000 字
- 最多 10 张图片（视频算1张图片）

**建议**:
- 技术文章：2000-5000 字
- 深度分析：5000-10000 字
- 图片数量：4-8 张

### 3.2 链接限制

**限制说明**:
- 外部链接需要通过微信审核
- 未认证公众号不支持外部链接
- 链接打开方式受限

**本工具的处理**:
```html
<!-- 链接会保留，但需要微信审核 -->
<a href="https://www.example.com" style="color: #7c3aed;">链接文本</a>

<!-- 建议：显示完整URL -->
官方网站：https://www.example.com
GitHub仓库：https://github.com/user/repo
```

### 3.3 视频/音频限制

**限制说明**:
- 只支持腾讯视频
- 音频只支持微信公众号音频素材库
- 不支持 `<video>` 或 `<audio>` 标签

**本工具不处理多媒体**:
- 视频/音频需要在微信编辑器中手动插入

---

## 4. 兼容性建议

### 4.1 浏览器测试

**推荐测试流程**:
1. Chrome/Edge 浏览器预览（开发阶段）
2. 微信编辑器预览（发布前）
3. 手机端预览（iPhone + Android）

**常见问题**:
- Chrome显示正常，微信显示异常 → 检查是否使用了不支持的CSS
- PC端正常，手机端异常 → 检查响应式样式

### 4.2 移动端优化

**响应式设计**:
```css
@media (max-width: 768px) {
  body {
    padding: 16px;
    font-size: 15px;
  }
  h1 { font-size: 24px; }
  table { font-size: 14px; }
}
```

**本工具已实现**:
- 移动端字体缩小 1px
- 标题大小自适应
- 表格、代码块自适应
- 图片宽度 100% 自适应

### 4.3 常见兼容性问题

**问题1：颜色显示不一致**
```css
/* ❌ 避免使用 */
color: rgba(0, 0, 0, 0.8);

/* ✅ 使用确定的颜色值 */
color: #333333;
```

**问题2：边框显示异常**
```css
/* ❌ 避免使用 */
border: 1px solid;

/* ✅ 明确指定颜色 */
border: 1px solid #dee2e6;
```

**问题3：背景渐变不显示**
```css
/* ⚠️ 部分设备不支持复杂渐变 */
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);

/* ✅ 提供纯色备选 */
background: #7c3aed;
background: linear-gradient(135deg, #7c3aed 0%, #3b82f6 100%);
```

---

## 5. 发布前检查清单

### 5.1 样式检查
- [ ] 所有样式都是内联的（无外部CSS）
- [ ] 没有使用不支持的CSS属性
- [ ] 颜色值使用十六进制（#ffffff）格式
- [ ] 字体使用系统字体栈

### 5.2 内容检查
- [ ] 文章长度 < 20,000 字
- [ ] 图片数量 ≤ 10 张
- [ ] 图片已上传到图床或准备在编辑器中上传
- [ ] 链接数量合理（认证号无限制，未认证号不支持）

### 5.3 格式检查
- [ ] 表格列数 ≤ 4 列（移动端友好）
- [ ] 代码块格式正确，换行和缩进保留
- [ ] 标题层级合理（H1 → H2 → H3）
- [ ] 段落间距适中

### 5.4 移动端检查
- [ ] 字体大小在移动端可读（≥ 15px）
- [ ] 图片在移动端正常显示
- [ ] 表格可横向滚动
- [ ] 代码块不超出屏幕

### 5.5 微信编辑器检查
- [ ] 粘贴到编辑器后样式正常
- [ ] 图片位置正确（需重新上传）
- [ ] 代码块格式保留
- [ ] 在手机上预览效果正常

---

## 6. 故障排除

### 问题1：粘贴后样式全部丢失

**可能原因**:
- 浏览器兼容性问题
- 复制方式不正确

**解决方案**:
1. 使用Chrome或Edge浏览器打开HTML文件
2. 按 `Ctrl+A` 全选内容
3. 按 `Ctrl+C` 复制
4. 在微信编辑器中按 `Ctrl+V` 粘贴
5. 如果还是丢失，尝试在浏览器中"检查元素"，复制 `<body>` 内的HTML代码

### 问题2：代码块格式混乱

**可能原因**:
- 微信编辑器自动格式化
- 代码中包含特殊字符

**解决方案**:
1. 粘贴后立即检查代码块
2. 如格式混乱，使用微信编辑器的"代码块"功能重新插入
3. 或使用代码图片替代（截图）

### 问题3：表格在手机上显示不全

**可能原因**:
- 表格列数过多
- 单元格内容过长

**解决方案**:
1. 减少表格列数（建议 ≤ 4 列）
2. 缩短单元格内容
3. 使用图片替代复杂表格
4. 或将表格拆分为多个小表格

### 问题4：图片无法显示

**可能原因**:
- 使用了本地图片路径
- 图片URL不可访问

**解决方案**:
1. 在微信编辑器中删除无法显示的图片
2. 点击"插入图片"重新上传
3. 或使用稳定的图床服务（如阿里云OSS、七牛云等）

### 问题5：链接无法点击

**可能原因**:
- 公众号未认证，不支持外部链接

**解决方案**:
1. 认证公众号（获得外部链接权限）
2. 或将链接改为纯文本显示
3. 或使用"阅读原文"链接

---

## 7. 最佳实践总结

### 7.1 内容创作建议
1. **控制长度**: 单篇文章 2000-5000 字最佳
2. **优化图片**: 使用图床，图片大小 < 1MB
3. **简化表格**: 列数 ≤ 4，避免复杂嵌套
4. **测试链接**: 确认所有链接可访问

### 7.2 样式设计建议
1. **使用主题**: 选择合适的预设主题（tech/minimal/business）
2. **保持简洁**: 避免过度装饰，突出内容
3. **颜色对比**: 确保文字和背景有足够对比度
4. **移动优先**: 优先考虑移动端阅读体验

### 7.3 发布流程建议
1. **本地预览**: 在浏览器中检查HTML效果
2. **复制粘贴**: 完整复制HTML内容到微信编辑器
3. **重新上传图片**: 替换本地图片为微信图片
4. **手机预览**: 在手机上预览发布效果
5. **调整优化**: 根据预览效果微调格式
6. **保存草稿**: 重要文章建议保存草稿备份
7. **正式发布**: 确认无误后发布

---

## 8. WeWrite 自动修复

以下微信平台限制已由 converter 自动处理，**无需手动干预**：

| 限制 | 自动修复 |
|------|---------|
| 外链被屏蔽 | 自动转为上标编号脚注 + 文末参考链接列表 |
| 中英文混排无间距 | CJK-Latin 边界自动插入空格 |
| 加粗文本后中文标点渲染异常 | 标点自动移到 `</strong>` 标签外 |
| 原生 `<ul>/<ol>` 列表渲染不稳定 | 自动转为 `<section>` + 样式化 bullet/number |
| 暗黑模式颜色反转错误 | 自动注入 `data-darkmode-color/bgcolor` 属性 |
| `<style>` 标签被剥离 | 所有 CSS 以内联 `style` 属性注入 |

这些修复在 `converter.py` 的 `convert()` 方法中自动执行，覆盖所有 16 个主题。

---

## 9. 参考资源

### 官方文档
- [微信公众平台 - 帮助中心](https://kf.qq.com/product/weixinmp.html)
- [微信公众号编辑器使用说明](https://mp.weixin.qq.com)

### 推荐工具
- **图床服务**: 阿里云OSS、七牛云、GitHub图床
- **浏览器插件**: 微信编辑器增强插件
- **Markdown编辑器**: Typora、VS Code、Obsidian

### 社区资源
- 搜索"微信公众号排版"获取更多技巧
- 参考优秀公众号的排版样式
- 使用浏览器"审查元素"学习别人的CSS技巧