企业官网建设流程全解析

简介：ep_headings2 是一款基于 JavaScript 开发的 Etherpad 标题插件，主要面向需要在在线协作文档中快速添加 h1 至 h6 等层级标题的编辑者，以及希望了解插件开发流程的技术人员。这一插件特别适合团队在 Etherpad 上进行长文档协作时使用，能够避免手动编写 HTML 标签，提高写作与审阅效率。该插件由 Etherpad 基金会维护，具备完善的功能特性：支持多语言翻译、导入导出、复制粘贴和活动标题显示，同时拥有较高的测试覆盖率并遵循代码规范，能显著提升长文档的结构化排版效率。压缩包共包含 54 个文件，整体大小约 86KB，其中 JSON 语言资源用来承载各语种翻译，JavaScript 实现标题插入的核心逻辑，CSS 负责外观样式，EJS 模板定义编辑器工具栏按钮，Markdown 文档提供使用与开发说明，目录结构清晰，方便直接部署或二次修改。目前已有 290 人学习下载。通过该资源，读者可以获取完整插件源码与配置样例，既可将其用于日常协作编辑场景，也能借鉴其中的测试组织、国际化处理以及插件打包思路，为后续开发同类 Etherpad 插件提供参考。

1. 默认标题只有一个级别：这是 ep_headings2 切入的痛点

1.1 长文档协作时，标题撑不起结构

如果你用 Etherpad 写过超过三页的会议纪要，多半见过这种场面：正文内容和章节标题长一个样，顶多粗一点、字大一点，翻到第 12 屏根本分不清哪里是新章节。默认工具栏里的 “Heading” 按钮，操作一次你就明白问题在哪——它不提供任何级别选择，点一下，整段变成同一种标题样式，想搞出“一级标题、二级标题、三级标题”的层级，基本靠手动改字号和颜色，改完还不一定统一。

ep_headings2就是冲着这个痛点来的。它是 Etherpad 插件体系里的第三方扩展，核心能力是给编辑器引入真正的多级标题结构：H1、H2、H3、H4 逐级定义，还能给每个级别单独指定颜色。安装之后，工具栏会多出一个标题下拉菜单，选中文字、点级别、完事，协作文档立刻有了层次。对经常用 Etherpad 写方案、做记录、维护知识库的团队来说，这个插件几乎属于刚需。

1.2 默认工具栏的“标题”为什么这么难用

我早期给团队部署 Etherpad 后，收到最多的反馈就是“文档没法看”。问题根源不在大家不会用，而在默认标题机制本身有三个先天缺陷。

第一，单级别限制。默认按钮只能施加一种 Heading 样式，没有层级关系。文档一旦超过两个章节，读者就没法通过标题快速定位，编辑者自己也需要反复滚动才能找到要改的地方。

第二，样式不可定制。标题颜色、大小全部跟随皮肤主题走。多个成员同时编辑时，有人用加粗冒充标题，有人用大字号冒充标题，格式一会儿就乱套了。缺乏一个统一的、一眼能识别的视觉规范。

第三，无法参与文档结构导出。Etherpad 默认的 HTML 导出会保留标题标签，但如果整个文档只有一种 Heading，导出到其它平台后结构信息基本等同失效，还得人工重新整理。

ep_headings2的出现，本质上是把 HTML 里的h1到h4概念搬进了 Etherpad 的编辑模型。它的实现思路并不复杂：在既有行属性系统上扩展一个heading属性，再把若干种标题级别暴露到工具栏，同时通过插件 CSS 控制各级标题的表现。搞清楚这条主线，后面无论装插件还是配样式，思路都会清晰很多。

2. 装插件前的环境准备：先把 Etherpad 从零跑起来

2.1 确认 Node.js 版本，这是第一道门槛

很多第一次接触 Etherpad 的朋友，最容易在环境准备阶段卡住，所以我把这一步单独拎出来说。Etherpad 是 Node.js 应用，版本兼容性直接决定你能不能正常安装插件，尤其像ep_headings2这种带前端资源包的插件，对 API 版本是有隐含要求的。

安装 Etherpad 前，先看官方对 Node.js 的要求。较新的 Etherpad 版本通常要求 Node.js 16 以上，部分维护版本需要 18 或 20；老版本则停留在 Node 12。判断方式很简单：命令行执行node -v，再看你准备装的 Etherpad release 版本，两者对齐就对了。

我建议直接用 NVM 管理 Node 版本，避免系统里多个项目互相干扰。这一步看似和标题插件无关，但版本不对导致的症状非常迷惑：插件面板里显示已安装，工具栏却永远不出现按钮，日志里还找不到报错。排查到最后往往是 Node 版本过旧，Etherpad 加载插件脚本时悄悄失败。

2.2 从源码跑通一个最小可用的 Etherpad

这里我给出一套经过验证的最小步骤，适合小白照着复制。先准备一个干净的目录，然后执行：

git clone --branch master https://github.com/ether/etherpad-lite.git cd etherpad-lite bin/installDeps.sh

Windows 环境下把最后一步换成bin/installDeps.bat。这个脚本会安装 Etherpad 自身的依赖，耗时取决于网络状况，耐心等就行。

依赖装好后，启动：

bin/run.sh

看到Report bugs at https://github.com/ether/etherpad-lite/issues以及类似HTTP server listening on port 9001的输出，就说明最小实例已经跑起来了。浏览器访问http://localhost:9001，能正常新建 pad，环境就算过了第一关。

2.3 启动日志里两个值得留意的信号

我每次搭完环境，会额外做两件事。第一，访问http://localhost:9001/admin，按提示创建管理员账号。虽然本地测试可以跳过，但后面用 Admin UI 装插件时还需要管理员权限，先配好免得回头再找。

第二，观察启动日志里有没有出现插件相关的加载信息。Etherpad 启动时会把扫描到的所有插件打印出来，如果你发现某些插件名后面有., 或者有明显的加载失败提示，说明node_modules里存在异常，需要先处理掉再继续。这一步虽然简单，但能帮你把“环境问题”和“插件本身问题”提前分开，后面排查会省很多时间。

3. 装 ep_headings2 的三种方法，以及我踩过的依赖坑

3.1 最快路径：npm 直接安装

进入 Etherpad 根目录，执行一行命令：

npm install ep_headings2

然后重启 Etherpad 服务。重启这一步不能省，Etherpad 的插件扫描发生在启动阶段，不像某些应用能热加载插件。

装完后回到 pad 页面，选中一段文字，工具栏上应该会出现一个标题下拉菜单，里面就是 H1 到 H4，选一个级别，文字立刻变成对应标题样式。如果没看到变化，先强制刷新浏览器，通常不是没生效，而是浏览器缓存。

这种安装方式的优点是干净、快，卸载也方便：

npm uninstall ep_headings2

它会同步清理package.json和node_modules里的相关条目，对后续维护很友好。

3.2 网页端插件管理器适合什么场景

如果你已经在用 Admin UI，也可以直接进入/admin/plugins，在搜索框输入ep_headings2，点搜索、点安装，剩下的事情由面板代劳。

这个方式最适合不太方便操作命令行的场景，比如基于 Docker 部署的 Etherpad，或者团队里其他人维护服务时。但我个人更偏爱命令行，原因有两点：一是安装输出更透明，能直接看到依赖解析过程；二是有些插件安装失败，在 Admin UI 里只给一个笼统的错误提示，排查起来反而不如命令行直观。

3.3 我在依赖方面的两次踩坑记录

第一次踩坑，是把ep_headings和ep_headings2同时装上了。这两个插件功能高度重叠，都会注册 heading 相关属性和工具栏按钮。装上第二天，团队成员就反馈工具栏按钮出现两套，一个旧一个新，点哪个都行为异常。后来我把ep_headings卸载，重启一次，恢复正常。

这件事给我的教训是：搜插件名时注意新旧版本关系。ep_headings2这个名字本身就暗示它是某个旧插件的替代品，安装前先看插件主页或 README，确认有没有需要先卸载的兄弟插件。

第二次踩坑发生在执行npm install ep_headings2时，因为权限不足而中断。我用sudo重新装后，插件倒是能用了，但在后续npm install升级其他插件时，出现依赖归属混乱的问题，排查下来才发现权限残留。我的建议是：Etherpad 目录如果放在普通用户可写的位置，就别轻易用sudo装插件；如果因为服务器环境必须用，至少保证后续所有 npm 操作都用同一权限，别混着来。

4. 把配置讲透：标题级别、颜色样式与 settings.json 的联动

4.1 插件装上后，编辑器内部发生了什么

使用ep_headings2时，选中一段文字并应用 H2 级别，Etherpad 并不会像普通编辑器那样直接把文字包进<h2>标签，而是在这一行的行属性上打一个标记，记录heading: h2。这个设计是 Etherpad 协作模型决定的：整个文档的文本和属性分开存储，属性通过操作转换算法在多人之间同步，所有在线成员才能在毫秒级内看到同一行标题的变化。

这个细节直接决定了插件的使用习惯。因为你打的标题标记本质上是一个行级属性，所以一个标题就是一行文字。想写一个层级完整的章节标题，通常就是独立一行，不要在前面放缩进空格，也不要在标题行中间用回车拆行。理解了这个内部结构，后面遇到问题就比较容易想明白。

4.2 settings.json 里的配置项到底管什么

ep_headings2的核心配置都集中在 Etherpad 根目录的settings.json里。不同版本默认值会有差异，但结构基本一致，下面是我实测可用的一个例子：

{ "ep_headings2": { "levels": ["h1", "h2", "h3", "h4"], "levelsAndColor": { "h1": { "color": "#c0392b" }, "h2": { "color": "#2980b9" }, "h3": { "color": "#27ae60" }, "h4": { "color": "#7f8c8d" } } } }

levels决定工具栏里出现哪些标题级别。如果你的协作文档不需要四级那么深，只留["h1", "h2", "h3"]就行。减少级别能让 Less 更少，新用户也不会被一堆按钮吓到。

levelsAndColor是给每个级别指定颜色。这一步对实际使用体验提升非常明显：一级标题红色加粗，二级标题蓝色，三级标题绿色。文档一屏之内五种颜色层次分明，读者扫一眼就知道结构。需要注意，颜色值是标准的 CSS 颜色写法，不支持color之外的属性，比如背景色、边框、字体大小，都不在这里配。

配置修改后同样要重启服务才生效。如果只是改颜色，不涉及级别增减，理论上前端刷新即可，但为了稳妥，我都是全局重启一次再验证。

4.3 想进一步定制标题外观怎么办

如果levelsAndColor不能满足你的视觉需求，比如想让二级标题带下划线，或者想调整标题字号，你可以把自定义 CSS 放进 Etherpad 的src/static/custom/目录，通过index.css覆盖插件默认样式。

我实际试过这种方式，改动全局字体和标题边距都没问题。但有一件事必须提醒：标题样式是所有打开这个 pad 的成员共享的。你给自己改一套深色主题样式，其他成员用浅色主题打开，就可能出现某个标题看不清的情况。

所以我的建议是：团队协作场景下，尽可能用插件自带的levelsAndColor指明要表达的视觉层级就够了，把复杂的自定义留到单独维护的界面主题里统一处理。

5. 实测遇到的四个问题与完整排查链路

5.1 问题一：按钮不出现，先查前端还是后端

如果你装完插件并重启后，工具栏死活看不到标题下拉菜单，不要急着怀疑插件没装好，按照下面的顺序排查。

先看启动日志。重启 Etherpad 时，日志里有没有出现ep_headings2字样？如果连日志都没有，说明插件根本没有被扫描到，检查npm ls ep_headings2是否在依赖列表里。

如果日志里有插件名但按钮不出现，九成是浏览器缓存问题。特别是用旧标签页打开 pad 时，前端资源可能还是旧版本。按Ctrl + F5强制刷新，或者无痕窗口重新登录一次，通常能解决。

有个容易被忽略的细节：Etherpad 的工具栏按钮在不同用户权限下显示不同。如果你用的是只读链接打开的 pad，工具栏会隐藏编辑类按钮。测试时务必使用可编辑链接或者已登录管理员账号，否则你会在“插件是不是坏了”的排查里绕很久。

5.2 问题二：与旧版 ep_headings 的冲突

症状最明显的场景是：安装ep_headings2后，工具栏里既有旧标题按钮又有新下拉菜单，点击旧按钮还会把已经设置为 H2 的标题重置回普通文本。

原因前面说过，两个插件都在操作 heading 属性，它们的规则在一个 pad 里是互斥的。处理方式很简单：卸载掉ep_headings，然后重启。如果你在 Admin UI 里看到两个插件都显示已启用，直接在新插件的设置里找冲突提示，通常会有明确警告。

这个冲突还提醒了一点：升级插件前先备份settings.json。因为某些插件升级后会把旧配置迁移到新格式，一旦迁移脚本不完整，标题颜色配置可能丢失。我因为没备份、重配色半小时的经历，至今印象深刻。

5.3 问题三：HTML 导出后标题“变异”

用 Etherpad 的 “Export HTML” 功能导出带标题的文档后，用浏览器打开，你会发现h1、h2标签其实都在，结构也没丢，但页面上标题颜色全变了，看起来像“变异”了。

这不是ep_headings2的 bug，而是导出机制决定的。插件设置的标题颜色由前端 CSS 注入，这个 CSS 只在 Etherpad 编辑器内部生效。导出的 HTML 是纯文件结构，依赖浏览器默认标题样式，颜色自然不一样。

解决方式有两个。一是导出后自行附加一段 CSS，给导出的 HTML 补上标题样式；二是在 Etherpad 里就用颜色值差异不大的方案，让标题即使丢掉自定义颜色，也能通过字号层级区分。实际导出时，我一般用前者，在 HTML 头部加个<style>块，把各级标题颜色和字体大小重新定义一遍。

5.4 问题四：多人同时编辑标题行时被“切碎”

在线协作时，两个人同时编辑同一行标题，一个在标题前面加序号，一个在标题后面补充说明，有时会看到这一行突然变成两行，或者标题样式只保留在其中一行上。

这其实是 Etherpad 行属性模型的正常现象。标题属性是针对整行存储的，当两个并发编辑操作把原本的一行拆成两个文本片段时，系统会为每个新行分别继承属性。于是，就出现了“标题被切碎”的观感。

要避免这个问题，团队成员需要形成一个基本习惯：标题行尽量作为独立段落维护，不要在标题文字中间随意换行。如果不小心发生样式分裂，也很容易修复，把多行文字选中后重新应用一次同级别标题即可，属性会统一回到同一级别上。

6. 我把这套组合部署进团队后的一些体会

最后说点来自实际使用的心得。我最早给团队装ep_headings2，只是图它能分出多级标题，后来发现真正让文档变清晰的，是搭配了不同级别颜色之后的视觉冲击力。红色一级、蓝色二级、绿色三级，一屏扫过去，哪里是章节、哪里是小节一目了然，连不习惯看文档层次的同事都开始主动用标题组织内容。

给新成员做交接时，我的建议很简单：不要一上来就讲配置项，先让他把一段没结构的文档用 H1、H2、H3 重排一遍，感受一个干净标题层级带来的差异。把这一步走通，再回去看settings.json里的 levels 和 color 配置，自然就理解了。

还有一个细节：任何插件升级前，先备份settings.json，再拍一下当前 pad 的标题样式截图。这样就算升级后配置有变化，也能立刻对照恢复。Etherpad 的插件系统整体很可靠，但该做的基本保护不能省，这是我在多次部署里换来的经验。

本文还有配套的精品资源，点击获取