StackEdit 6.0.12：让 Markdown 里的 HTML 不再"裸奔"

在线 Markdown 编辑器 StackEdit 发布了 v6.0.12，三个改动看似不大，却精准戳中了日常写作的痛点：HTML 标签终于能带样式了、图片格式不再挑食、PWA 回调地址也不再"串台"。下面逐个拆开看。

HTML 标签 + 安全 style：排版自由度的一大步

Markdown 本身对排版控制很弱——居中、字体颜色、背景高亮，全得靠嵌入 HTML。但此前 StackEdit 对 HTML 的处理偏保守，style 属性会被过滤掉，写进去的 <span style="color:red">重点</span> 渲染后只剩 <span>重点</span>，样式全丢。

6.0.12 放开了"安全"的 style 属性。所谓安全，是指不会引入 XSS 风险的 CSS 属性（如 color、background、text-align、font-size 等），而 position:fixed、javascript: 之类仍会被拦截。

实际效果——下面这段 Markdown 在 6.0.12 中可以正常渲染：

<span style="color: #e74c3c; font-weight: bold;">紧急：</span>该接口将在 2025-03-01 下线，请尽快迁移。

<div style="text-align: center; background: #f0f0f0; padding: 12px; border-radius: 4px;">
  <span style="font-size: 1.2em;">📢 公告标题</span>
</div>

<mark style="background: #fff3cd; padding: 2px 6px;">待确认</mark> 此处需要二次复核。

注意：style 白名单由 StackEdit 的 sanitizer 控制。如果你需要 position、z-index 等布局属性，仍会被过滤——这是有意为之的安全边界。

图片格式不再挑食

此前 StackEdit 对图片格式有隐式限制，部分格式（如 WebP、SVG、BMP）在粘贴或拖拽上传后无法正确预览或导出。6.0.12 扩展了图片处理管道，常见格式基本都能正常显示和嵌入。

日常写作中，这解决了几个具体场景：

• 截图直接粘贴：Windows 截图工具输出 BMP/PNG，macOS 截图默认 PNG，现在都能直接 Ctrl+V 进编辑器。
• 矢量图嵌入：架构图用 SVG 导出后，可以直接作为内联图片使用，放大不失真。
• WebP 压缩图：从网页保存的 WebP 图片不再需要手动转格式。

<!-- SVG 矢量图，放大不失真 -->
![架构图](./architecture.svg)

<!-- WebP 压缩图，体积小 -->
![截图](./screenshot.webp)

<!-- 标准 PNG -->
![流程图](./flow.png)

PWA 回调地址修复：不再"串台"

StackEdit 支持 PWA（Progressive Web App）模式，可以像原生应用一样安装到桌面。但 6.0.11 中，PWA 的 OAuth 回调地址会被"污染"——具体表现是：当你在 PWA 模式下登录 GitHub 或 Google 授权时，回调 URL 会指向错误的 origin，导致授权流程卡死或跳到空白页。

6.0.12 修正了 PWA manifest 中 start_url 和 scope 的处理逻辑，确保回调地址与实际运行 origin 一致。

如果你在自部署场景下遇到类似问题，检查 manifest 配置是个好习惯：

// public/manifest.json — 自部署时务必确认 start_url 与实际域名一致
{
  "name": "StackEdit",
  "short_name": "StackEdit",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "theme_color": "#1976d2",
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

自部署时，start_url 和 scope 必须与你的实际服务地址匹配。如果部署在 https://notes.example.com/stackedit/，那么：

{
  "start_url": "/stackedit/",
  "scope": "/stackedit/"
}

否则 PWA 安装后，OAuth 回调仍会指向错误路径。

自部署 StackEdit：一个最小可跑的 Docker 示例

如果你想在团队内部部署 StackEdit（避免公网授权风险、自定义存储后端），以下是一个最小 Docker Compose 配置：

# docker-compose.yml
version: "3.8"
services:
  stackedit:
    image: mafgwo/stackedit:6.0.12
    container_name: stackedit
    ports:
      - "8080:8080"
    environment:
      # 自部署时，按需配置 OAuth 回调地址
      - STACKEDIT_GOOGLE_CLIENT_ID=your-google-client-id
      - STACKEDIT_GOOGLE_CLIENT_SECRET=your-google-client-secret
      # GitHub OAuth（可选）
      - STACKEDIT_GITHUB_CLIENT_ID=your-github-client-id
      - STACKEDIT_GITHUB_CLIENT_SECRET=your-github-client-secret
    volumes:
      # 持久化工作空间数据
      - stackedit-data:/data
    restart: unless-stopped

volumes:
  stackedit-data:

启动命令：

# 拉取镜像并启动
docker compose up -d

# 查看运行状态
docker compose ps

# 访问编辑器
# 浏览器打开 http://localhost:8080

部署完成后，在 OAuth 提供方（Google / GitHub）的控制台里，把回调地址设为 https://notes.example.com/stackedit/oauth2/callback，与 manifest 中的 scope 保持一致即可。

升级建议与边界提醒

边界提醒：style 白名单不是全量 CSS——position、overflow、transform 等布局类属性仍被过滤，不要指望用它做复杂页面布局。Markdown + 安全 HTML 的定位是"增强排版"，不是"替代 CSS 框架"。

完整更新日志可对比 v6.0.11 → v6.0.12 的所有提交。如果你正在自部署旧版，建议直接跳到 6.0.12，PWA 回调修复和 style 支持都是不可回退的实际改进。