设置开发环境

相关源文件

• .eslintrc.json
• .gitignore
• src/_locales/fr/description.txt
• src/_locales/fr/markdown-here-image2.txt
• src/_locales/fr/md-for-screenshot.md.txt
• src/_locales/ru/description.txt
• src/_locales/zh_CN/description.txt
• src/_locales/zh_CN/markdown-here-image2.txt
• src/_locales/zh_CN/md-for-screenshot.md.txt
• src/_locales/zh_CN/screenshot-captions.txt
• src/common/options-iframe.html
• src/common/options-iframe.js
• test/index.html
• utils/build.js
• utils/package-lock.json
• utils/package.json

本文档提供了关于设置 Markdown Here 浏览器扩展开发环境的详细说明。它涵盖了为贡献或修改代码库所需的先决条件、代码组织、构建过程和测试方法。有关贡献指南和流程的信息，请参阅贡献指南；有关测试步骤，请参阅测试。

先决条件

在开始开发 Markdown Here 之前，请确保已安装以下工具：

工具	目的	要求
Node.js 和 npm	运行构建脚本和管理依赖	LTS 版本
Git	版本控制	任意最新版本
网页浏览器	测试扩展	Chrome、Firefox 和/或 Thunderbird

来源：utils/package.json2-11 utils/build.js6-12

存储库结构

Markdown Here 仓库的组织结构如下：

markdown-here/
├── dist/              # Build output directory (generated during build)
├── src/               # Source code
│   ├── common/        # Shared code across browser platforms
│   ├── chrome/        # Chrome-specific code
│   ├── firefox/       # Firefox/Thunderbird-specific code
│   └── _locales/      # Internationalization files
├── test/              # Test files
└── utils/             # Build scripts and utilities

项目结构图

来源：.gitignore8-9 utils/build.js15-22

设置本地环境

1. 克隆仓库

2. 安装依赖项

这将安装 `package.json` 中定义的所需 Node.js 包。

• archiver：用于创建扩展打包的 ZIP 存档
• file：处理文件系统操作
• glob：提供文件模式匹配
• markdown-it：用于 Markdown 渲染
• metascript：启用 JavaScript 文件的条件预处理

来源：utils/package.json5-11 utils/build.js10-12

开发环境架构

来源：utils/package.json5-11 utils/build.js15-22 test/index.html15-28

构建扩展

Markdown Here 的构建过程由 `utils/build.js` 脚本管理，该脚本用于为不同的浏览器平台打包扩展。

构建所有扩展：

此命令会在 `dist/` 目录中创建以下文件：

• chrome.zip：Chrome 扩展包
• firefox.zip：Firefox 扩展包
• thunderbird.xpi：Thunderbird 附加组件包

来源：utils/build.js19-21 utils/build.js155-159

构建过程工作流

构建脚本执行以下关键步骤：

1. 为每个目标平台（Chrome、Firefox、Thunderbird）创建 ZIP 存档
2. 遍历源目录以查找相关文件
3. 对于每个文件，检查它是否与不同平台的输入模式匹配
4. 使用 MetaScript 处理 JavaScript 文件以处理特定于平台的代码
5. 将处理后的文件添加到相应的 ZIP 存档中
6. 完成并将存档保存到 `dist/` 目录

来源：utils/build.js84-127 utils/build.js130-160 utils/build.js38-57 utils/build.js60-81

平台特定代码处理

Markdown Here 通过 MetaScript 的条件代码编译支持多种浏览器。在构建过程中，脚本会处理 JavaScript 文件，使其仅包含目标平台的代码。

这允许在支持不同浏览器扩展 API 的同时维护单个代码库。

来源：src/common/options-iframe.js7-21 utils/build.js64-69

测试扩展

手动测试

在开发过程中进行基本测试时，请使用 `test/index.html` 处的测试页面，该页面提供了一个可编辑内容的 iframe，用于测试 Markdown 切换功能。

浏览器特定测试

Chrome

1. 导航到 `chrome://extensions/`
2. 启用“开发者模式”
3. 点击“加载解压的扩展程序”
4. 选择 `src` 目录

Firefox

1. 导航到 `about:debugging#/runtime/this-firefox`
2. 点击“加载临时附加组件”
3. 选择 `src` 目录中的任意文件

Thunderbird

1. 首先构建扩展以生成 `.xpi` 文件
2. 在 Thunderbird 中，转到“工具”>“附加组件”
3. 点击齿轮图标并选择“从文件安装附加组件”
4. 从 `dist/` 目录中选择 `thunderbird.xpi` 文件

来源：test/index.html15-28

常见问题排查

问题	解决方案
构建脚本失败	通过在 `utils/` 目录中运行 `npm install` 确保所有依赖项都已正确安装。
扩展未在浏览器中加载	检查浏览器控制台是否有错误；验证您是否加载了正确的目录。
JavaScript 错误	检查浏览器的开发者控制台；对于 Chrome 扩展，检查后台页面。
平台特定代码问题	验证 MetaScript 条件语句是否正确格式化和闭合。
构建中缺少文件	检查 `utils/build.js` 中的平台特定输入模式。

来源：utils/build.js23-33 utils/build.js103-116

开发工作流

推荐的开发工作流程是：

1. 修改源代码
2. 在 `utils/` 目录中运行 `node utils/build.js` 来构建扩展
3. 在目标浏览器中加载扩展进行测试
4. 使用浏览器开发者工具进行调试
5. 根据需要迭代
6. 满意后，提交更改并创建拉取请求

来源：utils/build.js130-160 .gitignore1-13