wewrite/references/wechat-constraints.md

微信公众号平台限制说明

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

---

1. 核心技术限制

1.1 不支持外部CSS文件

限制说明:

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

本工具的解决方案:

<!-- ❌ 微信不支持 -->
<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属性:

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

支持的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

本工具的处理:

<!-- ❌ 微信不支持 -->
<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）
• 代码块中的换行和缩进容易丢失
• 不支持代码行号的动态生成

本工具的解决方案:

<!-- 使用<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

本工具的处理:

body {
  max-width: 720px;
  margin: 0 auto;
}

2.2 字体限制

限制说明:

• 微信不支持 @font-face 自定义字体
• 只能使用系统字体

本工具使用的字体栈:

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 表格限制

限制说明:

• 表格在移动端容易超出屏幕
• 复杂表格（合并单元格）支持有限

本工具的处理:

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 链接限制

限制说明:

• 外部链接需要通过微信审核
• 未认证公众号不支持外部链接
• 链接打开方式受限

本工具的处理:

<!-- 链接会保留，但需要微信审核 -->
<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 移动端优化

响应式设计:

@media (max-width: 768px) {
  body {
    padding: 16px;
    font-size: 15px;
  }
  h1 { font-size: 24px; }
  table { font-size: 14px; }
}

本工具已实现:

• 移动端字体缩小 1px
• 标题大小自适应
• 表格、代码块自适应
• 图片宽度 100% 自适应

4.3 常见兼容性问题

问题1：颜色显示不一致

/* ❌ 避免使用 */
color: rgba(0, 0, 0, 0.8);

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

问题2：边框显示异常

/* ❌ 避免使用 */
border: 1px solid;

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

问题3：背景渐变不显示

/* ⚠️ 部分设备不支持复杂渐变 */
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. 参考资源

官方文档

• 微信公众平台 - 帮助中心
• 微信公众号编辑器使用说明

推荐工具

• 图床服务: 阿里云OSS、七牛云、GitHub图床
• 浏览器插件: 微信编辑器增强插件
• Markdown编辑器: Typora、VS Code、Obsidian

社区资源

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