Prompt

在线 Markdown 编辑器开发方案

第一阶段：核心功能搭建 (MVP)

这个阶段的目标是搭建一个基础可用的编辑器页面，集成 Milkdown，并实现核心的“延迟上传”图片处理逻辑。

1. 页面与路由搭建
   • 在 app 目录下创建一个新的路由用于文章创作，例如 app/create/page.tsx。
   • 此页面将包含用于设置文章元数据（Frontmatter）的表单：
     • 一个用于输入文章标题 (title) 的 <input> 组件。
     • 一个用于输入文章描述 (description) 的 <textarea> 组件。
     • 一个用于输入标签 (tags) 的组件（例如，一个简单的、用逗号分隔的文本输入框）。
     • 一个用于设置文件名的 <input> 组件。
   • 页面还将包含一个用于安放 Milkdown 编辑器的 <div> 容器。
   • 页面顶部需要包含一个“发布”按钮，用于触发后续的图片上传和文章提交流程。
2. 编辑器组件封装
   • 创建一个新的 React 组件，例如 components/Editor.tsx，并在其文件顶部声明 "use client;"，因为 Milkdown 是一个纯客户端组件。
   • 在该组件内部，初始化 @milkdown/crepe 编辑器。
   • 关键：实现图片延迟上传逻辑
     • 配置 Milkdown 的 onUpload 回调函数。当用户粘贴、拖拽或选择图片时，此函数被触发。
     • 在此回调函数中，我们不立即上传图片，而是：
       1. 接收传入的 File 对象。
       2. 使用 URL.createObjectURL(file) 生成一个本地的 blob: URL。
       3. 维护一个 Map<string, File> 对象，将 blob: URL 和原始 File 对象关联起来并存储。
       4. 将 blob: URL 返回给 Milkdown，编辑器会立即显示图片，实现“即时”预览效果。
     • 需要注意使用 useEffect 的 cleanup 函数，在组件卸载时调用 URL.revokeObjectURL() 来释放内存，避免内存泄漏。
3. 用户认证集成
   • 我们将使用 NextAuth.js 来保护创作页面和后续的 API 接口。
   • 创作页面 (/create) 将成为一个受保护的路由。未登录的用户访问时，将被重定向到登录页。
   • 这可以通过在 page.tsx 中获取服务端 session 来实现。

第二阶段：图片上传与处理

这个阶段的核心是实现从浏览器到 Cloudflare R2 的安全上传，并将文章内容中的 blob: URL 替换为最终的线上地址。

1. 创建后端 API - 获取预签名 URL
   • 在 app/api/upload/route.ts 创建一个新的 API 路由。
   • 这个路由将处理 POST 请求，其核心职责是生成用于上传到 Cloudflare R2 的预签名 URL (Presigned URL)。
   • 安全保障:
     1. 使用 NextAuth.js 的 auth() 辅助函数对该 API 进行保护，确保只有已登录的用户才能请求上传链接。
     2. 从 session 中获取当前用户的 ID。
   • 处理流程:
     1. 客户端在请求 Body 中附带文件名、文件类型等信息。
     2. 服务端根据这些信息，结合用户ID、当前时间戳和文章标题（由客户端一并传来），生成一个唯一的、有组织的对象键（Object Key），例如：users/{userId}/{document-slug}/{timestamp}-{filename}。这确保了文件的归属清晰，便于未来管理。
     3. 使用 @aws-sdk/s3-request-presigner 和 @aws-sdk/client-s3 (已配置为指向 R2) 生成一个有时效性的 PutObject 预签名 URL。
     4. API 将这个预签名 URL 和最终用于访问图片的公开 CDN URL 一并返回给客户端。
2. 实现前端发布逻辑
   • 当用户点击“发布”按钮时，触发以下客户端逻辑：
     1. 从 Milkdown 编辑器实例中获取完整的 Markdown 内容字符串。
     2. 遍历之前存储的 Map<blobUrl, File>。
     3. 对于 Map 中的每一个 File 对象：
        • 调用我们创建的 /api/upload 接口，获取 R2 的预签名 URL 和最终的公开 URL。
        • 使用 fetch API，以 PUT 方法将 File 对象直接上传到获取到的预签名 URL。
        • 使用 Promise.all 等待所有图片都上传完毕。
     4. 所有图片上传成功后，遍历原始的 Markdown 字符串，将其中所有的 blob: URL 批量替换成它们对应的最终公开 URL。

第三阶段：文章发布与整合

此阶段的核心是将在编辑器中创作的内容与现有基于 GitHub URL 的投稿流程进行整合。现有系统并非通过后端 API 提交，而是引导用户到 GitHub 网站上完成操作。

1. 整合现有投稿流程
   • 在所有图片上传完毕、Markdown 内容中的 blob: URL 也被替换为线上 URL 后，点击“发布”按钮的最终操作将触发一个与现有 Contribute.tsx 组件类似的流程。
   • 可以复用或改造 Contribute.tsx 中的目录选择对话框，让用户选择新文章在 app/docs/ 目录下的存放位置。
2. 构建最终文件内容并跳转
   • 用户选定目录后，系统将执行以下操作：
     1. 组合 Frontmatter: 根据第一阶段中用户在表单中输入的标题、描述、标签等信息，以及自动生成的当前日期 (date) 生成标准的 Frontmatter 字符串。
     2. 拼接完整内容: 将生成的 Frontmatter 字符串与 Milkdown 编辑器产出的 Markdown 内容拼接在一起，形成最终的完整文件内容。
     3. 生成 GitHub URL: 调用 buildGithubNewUrl 函数（该函数已存在于 Contribute.tsx 中），将用户选择的目录路径、文件名以及 Base64 编码后的完整文件内容作为参数，生成一个指向 GitHub 新建文件页面的 URL。
     4. 跳转到 GitHub: 使用 window.open 打开这个新生成的 URL。
3. 用户在 GitHub 完成后续操作
   • 页面将跳转到 GitHub，此时新建文件的内容（包括 Frontmatter 和文章主体）已经被完整填充。
   • 用户将按照现有的 CONTRIBUTING.md 指南，在 GitHub 上手动完成后续的 Commit changes 和创建 Pull Request (PR) 的步骤。
   • 通过这种方式，我们成功复用了项目“引导用户去 GitHub 提交”的核心逻辑，同时为用户提供了强大的在线编辑和图片处理能力。

这个方案将整个流程分解为三个清晰的阶段，优先实现核心的编辑器体验，然后是关键的图片上传，最后与现有系统集成。采用预签名 URL 的方式，可以最大程度地减轻 Vercel Serverless Function 的负载，提升上传性能和安全性，非常适合该项目的技术栈和部署环境。

未来计划