Copy as Markdown开发指南：从源码到浏览器扩展的完整流程

Copy as Markdown开发指南：从源码到浏览器扩展的完整流程

【免费下载链接】copy-as-markdownA browser extension to copy tabs and links as Markdown项目地址: https://gitcode.com/gh_mirrors/co/copy-as-markdown

Copy as Markdown是一款强大的浏览器扩展，能够帮助用户将标签页和链接以Markdown格式快速复制。本指南将带你了解从源码到浏览器扩展的完整开发流程，适合新手和普通用户学习如何构建和定制这款实用工具。

准备工作：开发环境搭建

在开始开发之前，需要确保你的环境满足以下要求：

• Node.js >= 20
• 通过npm install安装项目依赖
• 全局安装web-ext工具：npm install -g web-ext（用于Firefox打包和调试）
• Docker（运行完整的端到端测试套件时需要）

获取项目源码的方法非常简单，只需执行以下命令：

git clone https://gitcode.com/gh_mirrors/co/copy-as-markdown

项目结构解析：了解代码组织

Copy as Markdown的项目结构设计清晰，便于维护和扩展。核心目录结构如下：

src/ # 共享源代码 background.ts # MV3服务工作线程/Firefox事件页面入口 handlers/ # 消息/命令/上下文菜单处理器 services/ # 浏览器无关逻辑（+通过createBrowser*助手的浏览器适配器） ui/ # 弹出窗口/选项脚本 static/ # HTML页面和静态资源（原样复制） chrome/ # Chrome/Chromium目标 — manifest.json + dist/（已构建） firefox-mv3/ # Firefox MV3目标 — manifest.json + dist/（已构建） test/ e2e/ # Playwright端到端测试 ui/, lib/ # vitest浏览器测试（真实Chromium） **/*.test.ts # vitest单元测试（node）

这种结构将平台特定代码与共享代码分离，通过构建脚本将共享代码复制/捆绑到每个目标的dist/目录中，有效解决了浏览器兼容性问题。

核心功能开发：从服务到处理器

架构概览

项目采用了清晰的分层架构，主要包括以下几个部分：

• 服务（Services）：包含纯逻辑（链接/标签导出、选择转换）以及通过createBrowser*助手创建的轻量级浏览器适配器。浏览器依赖项被注入以方便测试。

• 处理器（Handlers）：编排用户入口点（上下文菜单、键盘命令、运行时消息）并委托给服务。

• UI：src/ui下的脚本驱动弹出窗口/选项页面；静态资源位于src/static。

关键源代码文件

以下是一些核心功能的源代码文件，你可以通过阅读这些文件来深入了解项目实现：

• 链接导出功能：services/link-export-service.ts
• 标签导出功能：services/tab-export-service.ts
• 选择转换功能：services/selection-converter-service.ts
• 上下文菜单处理：handlers/context-menu-handler.ts
• 键盘命令处理：handlers/keyboard-command-handler.ts

构建扩展：从源码到可安装文件

基本构建命令

使用以下命令可以构建扩展：

npm run build # 构建chrome/和firefox-mv3/ npm run build-chrome # 仅构建Chrome（+断言Turndown不存在于SW捆绑包中） npm run build-firefox-mv3 # 仅构建Firefox npm run package # 构建+压缩/web-ext构建商店制品到build/

构建过程由esbuild驱动，详细的构建机制可以参考docs/build.md。

开发调试

在开发过程中，你可以使用以下命令进行自动重载调试：

npm run debug-chrome # Chrome自动重载调试 npm run debug-firefox-mv3 # Firefox自动重载调试

如果需要手动加载扩展（无自动重载）：

• Chrome：扩展程序 → 加载已解压的扩展程序 → 选择chrome/目录。
• Firefox：工具 → 附加组件 → 齿轮图标 → 调试附加组件 → 临时加载附加组件。

测试策略：确保扩展质量

单元测试和浏览器测试

项目使用vitest进行测试，分为两个项目：

• unit（node环境，test/**/*.test.ts）
• browser（通过Playwright使用真实Chromium，test/ui/**和test/lib/**）

这些测试不会触及系统剪贴板，因此可以在任何地方运行，无需Docker。

npm test # 运行所有vitest项目一次 npm run test:watch # 监视模式 npm run test:ui # vitest UI npm run test:unit # 仅单元项目 npm run test:browser # 仅浏览器项目

端到端测试

扩展UI和剪贴板流程使用Playwright进行端到端测试。测试在有头模式下运行Chromium，使用持久配置文件（Chrome扩展所需）。

完整的端到端测试套件必须在Docker中运行：

npm run test:e2e:docker

这将运行docker/playwright-ci/docker-e2e.sh脚本，构建Docker镜像并在容器中运行测试套件。

对于Firefox，项目还提供了基于Python/pytest的端到端测试，通过Selenium驱动：

npm run test:e2e:selenium

打包与发布：分享你的扩展

Firefox扩展打包

要测试Firefox的重启行为（例如上下文菜单是否重新安装），你需要构建并侧载XPI文件。Firefox检查XPI签名，在发布版Firefox中无法禁用此功能，因此建议使用开发者版、Nightly或未品牌化的Beta版。

1. 执行npm run package-firefox-mv3，XPI文件将保存在./build/firefox-mv3中。
2. 在Firefox开发者版中，打开about:config，将xpinstall.signatures.required设置为false，然后重启。
3. 打开about:addons，将XPI拖放到页面上进行安装。
4. 重启浏览器以验证重启行为。

扩展签名

要在发布版Firefox上侧载扩展，需要通过AMO签名：

1. 从Firefox附加组件获取API密钥。
2. bumpmanifest.json中的版本（AMO要求X.Y.Z，全部为数字，无前缀零）。
3. 运行：

web-ext sign --channel=unlisted --api-key=... --api-secret=...

这将创建一个用你的AMO账户签名的XPI，并将其上传为未列出的扩展。

结语：开始你的扩展开发之旅

通过本指南，你已经了解了Copy as Markdown从源码到浏览器扩展的完整开发流程。这个项目不仅提供了实用的功能，还展示了现代浏览器扩展开发的最佳实践。无论你是想定制这个扩展，还是开发自己的浏览器工具，这些知识都将帮助你顺利开始。

如果你想进一步探索，可以查看项目中的fixtures/qa.html文件，它收集了各种边缘情况，有助于你更全面地测试扩展功能。祝你在浏览器扩展开发的道路上取得成功！

【免费下载链接】copy-as-markdownA browser extension to copy tabs and links as Markdown项目地址: https://gitcode.com/gh_mirrors/co/copy-as-markdown