网页里要放一个能写代码的框这种需求比想象中多得多。低代码平台的函数面板、后台系统的 SQL 查询框、接口调试工具的请求体编辑区、在线学习网站的练习题输入框……凡是希望用户输入的内容能像 IDE 一样带高亮、带行号、能折叠就不可能继续用 textarea 硬扛。我第一次正经接触 Ace 在线代码编辑器是在一套低代码平台里做逻辑片段编辑从最基础的初始化到后来处理各种奇怪布局问题前前后后折腾了不少时间这篇文章把可以直接用的经验整理出来。Ace 是一个纯前端实现的网页代码编辑器组件不需要后端配合引入之后通过几个配置项就能获得语法高亮、代码折叠、行号、自动补全和搜索替换这些接近桌面 IDE 的能力。它适合的场景很明确需要在网页里编辑 JavaScript、Python、SQL、JSON、Markdown 等文本内容并且希望编辑体验比 textarea 高一个档次但又不想从零实现一个编辑器的团队。这篇文章面向的是准备接 Ace、或者已经接入但时不时被一些怪问题卡住的开发者我会按实际接入顺序来写从选型对比到基础初始化再到业务联动和踩坑排查最后补一些进阶玩法。1. 选型那点事为什么我会把 Ace 放进生产环境1.1 先判断你要的是编辑器还是输入框很多团队在调研阶段就犯了个错误一听说“网页上加代码编辑器”马上开始对比各种编辑器组件折腾了一两周发现根本用不上。所以第一步其实是忍住先问自己三个问题用户需要编辑的到底是什么格式的内容如果是纯文本、少数几行备注textarea 加个等宽字体就够了没必要引入任何编辑器。用户需要在编辑时看到什么如果只是“输入一段文字再提交”那就没有高亮、行号、折叠这些硬需求。未来会不会在同一个位置放多个语言的内容比如既是 JSON 配置又可能是 SQL 查询这直接决定了要不要考虑动态切换语法模式的能力。我遇到过最典型的需求是一个内部运维系统的配置管理页面用户要在线修改一份类似 YAML 的配置。一开始同事真的用了 textarea老员工用得难受后来换了 Ace反馈立刻不一样了。这种场景就是 Ace 的舒适区内容语法化、需要高亮、需要行号定位但不需要完整的调试器和断点能力。1.2 横向对比一下Ace 的赢面在哪代码编辑器的前端方案圈子里绕不开的就是 Ace、CodeMirror 和 Monaco 这几个。我不展开聊源码只从落地维护的角度给个对比表对比维度AceCodeMirrorMonaco体积与加载相对轻量mode/theme 可按需加载也较轻量模块化设计偏重通常要按需拆包上手成本低几行代码就能跑起实例中等新版模块化学习曲线略高中高初始化参数较多补全与语法能力自带基础补全可注册自定义补全源需要组装扩展灵活性高但费事原生补全和智能提示很强典型场景中后台页面、低代码平台、配置编辑富文本编辑、博客后台、表单类需求大型在线 IDE、需要贴近 VS Code 体验的产品我自己的选型逻辑很简单如果产品的核心就是“在网页里改代码”而且用户体验对标的是专业 IDE那 Monaco 值得考虑如果只是“用户的表单里有一段结构化的文本需要友好编辑”Ace 的性价比最高。而且 Ace 对旧浏览器环境的兼容性、对移动端简单的只读预览都做得比较务实这在很多企业内部系统里反而是最重要的点。2. 5 分钟跑通最小实例基础集成与初始化细节2.1 引入方式注意包名别装错Ace 的官方构建产物发布在包管理器上但这里有个经典的坑早期项目里容易把包名记成ace实际应该安装的是ace-builds。前者更多是历史遗留的模块后者才是包含构建后静态资源的发布包我们团队第一次接的时候就在包名上白花了十来分钟。如果用打包工具推荐按需引入模式npm install ace-builds然后在代码里导入核心模块和目标语言、主题import ace from ace-builds; import ace-builds/src-noconflict/mode-javascript; import ace-builds/src-noconflict/theme-monokai;如果你只是做一个后台页面不想折腾打包配置也可以直接用 script 标签引入ace.js主文件。两种方式都行但我的建议是版本一定要锁死不要用浮动版本号。Ace 的 API 大部分很稳定但少数边缘行为在不同版本之间有过调整线上环境里“昨天还好好的今天突然报错”这种事多半是浮动版本自动升上去了。2.2 创建第一个编辑器实例Ace 的使用逻辑非常直接页面里先放一个普通 div然后让 Ace 接管它。看一个最小例子div idcodeEditor styleheight: 360px;/divconst editor ace.edit(codeEditor); editor.session.setMode(ace/mode/javascript); editor.setTheme(ace/theme/monokai); editor.setValue(function hello() {\n console.log(hello ace);\n});这里有三件事需要解释清楚。第一ace.edit(codeEditor)接收的是一个元素 id也可以直接传 DOM 元素对象。它会在这个 div 内部创建一层绝对定位的编辑器层所以承载编辑器的容器必须要有明确的宽高这点后面踩坑部分还会重点讲。第二setMode是设置语法模式ace/mode/javascript表示 JavaScript。命名空间前缀ace/mode/不能漏否则会匹配不到对应的高亮规则。setTheme同理前缀是ace/theme/。第三setValue只是最基础的赋值方式。它默认会把光标定位到内容末尾这在回显历史数据时会让用户很别扭后面我会讲怎么用第二个参数把光标移到开头。2.3 三种常见接入形态固定高度、自适应高度、只读预览业务里遇到的接入形态基本可以归成三类我分开说。固定高度是最简单的给容器设一个固定 height编辑器自然撑满。适合做后台表单里的代码字段。自适应高度适合内容长短不确定的场景比如在线配置项当内容只有两行时一个 400px 高的空白编辑器很难看。Ace 提供了 minLines 和 maxLines 配置editor.setOptions({ minLines: 5, maxLines: 20, autoScrollEditorIntoView: false });设置之后编辑器会跟随内容行数自动伸缩超过 maxLines 后出现内部滚动条。这个配置看着冷门实际用起来体验提升非常明显。只读预览则适合展示代码片段或查看日志只需要editor.setReadOnly(true)。我甚至会在一些详情页面把 Ace 当语法高亮的展示器用省去额外引一个高亮库的麻烦。3. 别急着写功能模式、主题、字体这些高频配置3.1 语法模式静态引入和动态切换语法高亮是代码编辑器最基本的门面。Ace 内置了几十种语言模式常见的 JavaScript、Python、Java、SQL、JSON、Markdown、HTML、CSS 都在里面。如果你喜欢甚至可以去文档里找到对应的 mode 目录逐个看支持哪些语言。这里要特别注意一种情况使用打包工具按需引入时不会默认加载所有 mode。你想用 Python就需要显式引入一次import ace-builds/src-noconflict/mode-python;引入之后运行时切换模式就是一行代码的事editor.session.setMode(ace/mode/python);我常做的一个设计是编辑器上方放一个语言选择下拉框用户选择后动态切换 mode。这种交互在“配置中心”“查询平台”这类系统里很常见因为同一块编辑区域可能既允许写 SQL又允许写脚本。只要把需要的 mode 提前打包好切换几乎是瞬时的体验很顺。3.2 主题与行内视觉细节别让用户觉得廉价Ace 的主题很多从浅色的textmate、chrome到深色的monokai、dracula、tomorrow_night基本覆盖了主流代码配色风格。主题切换同样一行代码editor.setTheme(ace/theme/dracula);除了主题有几个默认行为值得看一眼它们直接决定编辑器用起来“专业不专业”highlightActiveLine默认高亮当前行建议保留写长代码时找光标位置省力很多。showPrintMargin默认在 80 列位置显示竖线如果团队没有统一的换行规范建议关掉否则用户在宽屏下总觉得自己写超了。showGutter控制左侧行号栏默认开启一般不用动。wrap是否软换行。编辑 SQL 或长文本时建议开启避免横向滚动条逼疯用户编辑代码片段时可以关闭以保持格式原样。这些配置都可以用editor.setOptions({ ... })一次性传进去。我个人的习惯是把它们固化成一套项目级默认配置封装成一个函数所有编辑器实例统一走这个入口省得每个页面复制粘贴。3.3 自定义标记业务最需要的高亮扩展很多产品对编辑器的要求不只是语法高亮还要把特定的内容标出来。比如在配置系统里把“危险操作”那段代码标红在 SQL 编辑器里把被禁止的字段名标出来。这种需求用 Ace 的 marker 机制可以轻松实现const Range ace.require(ace/range).Range; editor.session.addMarker( new Range(0, 0, 2, 10), danger-block, fullLine );然后配合一段 CSS.danger-block { position: absolute; background: rgba(255, 0, 0, 0.15); border-radius: 2px; }这个能力比一般人想象中强大。它不是简单画个背景色而是可以基于行、基于选区做高亮还能动态移除、动态更新。如果你要做一个带审计性质的编辑器这个 API 几乎是最短的实现路径。4. 核心业务联动读取值、赋值、表单校验与后端保存4.1 取值别想当然注意内容的边界情况编辑器里的内容最终要通过editor.getValue()拿回来。这个方法返回当前全部文本行为上和普通 textarea 的 value 基本一致但有个容易被忽视的细节当编辑器最后一行是空行时不同的操作可能产生不同的尾行处理结果。真正要提交数据前不要直接拿 raw value 去跟后端比建议先做一次 trimconst rawValue editor.getValue(); const cleanValue rawValue.replace(/\r\n/g, \n).trim();换行符统一也很重要。Windows 和 Unix 的换行差异会造成很多诡异的问题尤其在配置比对、签名校验场景。我的做法是保存时统一转成\n回显时不做额外处理让 Ace 自己适配。4.2 回显赋值与光标定位核心体验细节setValue的第二个参数很多人不知道。默认情况下赋值后光标会跑到内容最末尾如果你回显一段历史脚本用户可能想从头检查改动结果一进来光标在最后一行方向感很差。解决办法是传-1editor.setValue(savedContent, -1);这个参数表示光标位置-1代表开头。实测下来历史数据回显用这个姿势用户上手基本不会有“咦我内容呢”的疑问。另外Ace 的值和前端框架的状态不是一个天然联动的关系。它不会像 checkbox 那样自动在表单提交时带上数据所以你需要手动监听 change 事件editor.session.on(change, () { onChange(editor.getValue()); });注意别做成死循环如果你在 change 回调里又调用setValue会再次触发 change。正确做法是先判断新旧值是否一致再做赋值或者在程序性赋值时临时断开监听。4.3 表单校验和错误提示别只弹一个 alert中后台系统里最常见的场景是编辑器里填一串 JSON提交后告诉用户“格式错误”。这个流程如果只弹一个 alert用户根本不知道错在哪一行。Ace 提供了一个叫注解annotation的机制可以把错误直接标到对应行上try { JSON.parse(editor.getValue()); editor.session.clearAnnotations(); } catch (err) { const errorRow 0; // 实际可以根据 err 位置解析 editor.session.setAnnotations([ { row: errorRow, col: 0, text: JSON 格式错误 err.message, type: error } ]); }效果是在行号栏出现一个感叹号图标鼠标悬停能看到错误信息。对于 SQL、脚本类内容配合后端返回的错误行号可以把报错位置标注得特别精准。这块做好了工具的“专业感”是能直接感知到的。4.4 提交保存的完整套路结合前面的内容一个干净的提交逻辑大概是saveBtn.addEventListener(click, async () { const value editor.getValue().trim(); if (!value) { alert(内容不能为空); return; } const res await fetch(/api/config/save, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ content: value }) }); // 根据返回结果决定是否 setAnnotations });保存前做本地校验保存后根据后端响应决定是否展示错误注解这个链路我基本在每套使用了 Ace 的系统中都会搭一遍。5. 线上踩坑实录我在实际项目中遇到过的 5 个问题5.1 编辑器高度为 0整个面板塌掉了Ace 的渲染层是绝对定位填充进容器的所以容器高度必须真实存在。我第一次接入时就是随手写了个没有 height 的 div结果页面加载完编辑器区域直接是 0 高度滚动条和内容全都消失。解决方式很简单给承载编辑器的最外层单独设置高度不要依赖内容自适应。如果是自适应的 minLines/maxLines 方案也要确保在初始化前样式已生效。初始化之后再加 height 不一定能触发 Ace 重新计算最好写容器内联样式。5.2 弹窗、Tab 切换之后编辑器空白或光标错位这个问题是同类坑里最高发的编辑器初始化的瞬间它所在的弹窗是隐藏的宽度高度都是 0Ace 就会按 0 尺寸渲染。等弹窗真正显示时编辑器没有感知到尺寸变化表现就是一片空白或者文字挤在最左边。标准解法是让编辑器在能拿到真实尺寸后主动重算function showDialog() { dialog.style.display block; requestAnimationFrame(() { editor.resize(); }); }如果容器尺寸会持续动态变化更稳的做法是挂一个尺寸观察器const observer new ResizeObserver(() editor.resize()); observer.observe(editorContainer);注意观察的是容器元素不是编辑器内部元素。这个方法我用在左侧菜单折叠时会改变宽度的页面里效果很稳定。5.3 setValue 之后光标跳到末尾用户一脸懵这个前面提过但值得再强调一次。前端准备升级 Ace 的时候最容易让业务方吐槽的不是高亮不好看而是“我打开历史配置想改第一行结果光标在最后一行”。当时我还以为功能区没渲染好排查了半天才发现是 setValue 光标位置的问题。修复就一行editor.setValue(content, -1);我自己后来封装编辑器组件时已经把第二个参数写死成-1所有回显场景统一走这个入口再也没被这个问题找过。5.4 动态创建编辑器之后内存泄漏页面越来越卡Ace 实例会绑定大量 DOM 和事件。如果你在一个单页应用里反复打开弹窗、每次 new 一个编辑器又不销毁旧实例页面很快就会开始发钝。正确的做法是在组件卸载、弹窗关闭时调用销毁方法editor.destroy();另外如果你在同一个 div 上重复调用ace.edit(xxx)Ace 会检测到已经初始化过直接报错或返回旧的实例。这个行为在有缓存逻辑的框架里很容易踩中建议统一封装一个“编辑器管理池”按容器 id 存实例二次打开时直接复用不要重新创建。5.5 中文输入法下的特殊字符输入异常这个坑比较偏但国内团队大概率会碰到。在中文输入法开启时如果连续快速输入Ace 偶尔会出现候选词丢失、拼音和上屏内容错乱的现象尤其是在旧版本上更为明显。社区里讨论过很多次本质上是编辑器对浏览器输入法组合事件的处理还不够完善。我的实际处理经验是优先升级到当前较新的稳定版本很多输入法相关的问题随着版本迭代已经在逐步改善然后在目标团队常用的浏览器里覆盖“中英文混输、快速删改”的回归用例。如果实在是某个特定环境绕不过去可以考虑在输入法组合期间把编辑器临时切为只读等输入结束再恢复虽然交互上有一点牺牲但至少不会产生内容错乱。这个取舍需要在真实业务上验证别在测试环境拍脑袋决定。6. 进阶玩法自动补全、代码折叠与快捷键自定义6.1 自动补全从内置单词补全到远程候选词Ace 的自动补全可以做得比想象中灵活。先启用语言工具扩展和基础补全import ace-builds/src-noconflict/ext-language_tools; editor.setOptions({ enableBasicAutocompletion: true, enableLiveAutocompletion: true });这样输入代码时会基于当前内容里的单词给出提示。但业务里往往需要自定义补全比如把数据字典里的字段名作为候选词或者把常用的 SQL 模板做成补全项。这时可以注册自定义补全源const remoteCompleter { getCompletions(editor, session, pos, prefix, callback) { if (prefix.length 2) { callback(null, []); return; } // 假设这里从接口拉取候选词 const suggestions [ { caption: username, value: username, meta: 字段 }, { caption: status, value: status, meta: 字段 } ].filter((item) item.caption.startsWith(prefix)); callback(null, suggestions); } }; editor.setOptions({ enableBasicAutocompletion: [remoteCompleter], enableLiveAutocompletion: true });把远程候选词接进来之后编辑器就从一个“好看的高亮框”变成了真正能提效的业务工具。我自己做的数据查询平台里联表字段补全这个功能上线之后用户写 SQL 的时间肉眼可见地降了。6.2 代码折叠与搜索替换代码折叠默认在 JavaScript、Java 这类大括号语言里是开箱即用的行号栏会出现折叠箭头。如果觉得折叠粒度不理想可以设置折叠风格editor.session.setFoldStyle(markbegin);搜索替换是另一个容易被忽略但高频使用的功能。引入搜索框扩展后按 CtrlF 打开查找面板import ace-builds/src-noconflict/ext-searchbox; editor.find(TODO, { wrap: true, caseSensitive: false }); editor.findNext();如果只选中一处用editor.replace(已完成)需要整篇替换可以先editor.findAll(TODO)选中所有匹配项再调用替换。这个组合在批量修改历史配置时非常有用比手翻强太多。6.3 自定义命令把常用操作绑成快捷键Ace 自带一套常见命令但你完全可以给团队场景定制专属快捷键。举一个我常用的例子在配置编辑器里一键插入当前时间戳。editor.commands.addCommand({ name: insertTimestamp, bindKey: { win: Ctrl-Alt-T, mac: Command-Alt-T }, exec(editor) { const cursor editor.getCursorPosition(); editor.session.insert(cursor, /* new Date().toLocaleString() */); editor.focus(); } });这里有个小细节命令的name要保证全局唯一否则可能会覆盖掉 Ace 内置命令。比如如果用已有的find做名字整个搜索功能就被你改了。建议统一前缀管理比如app-timestamp。最后说一点我个人的体会。Ace 这类东西最大的坑往往不是 API 不会用而是布局时机和生命周期管理。如果你准备把它用到生产环境建议一开始就封装成一个独立组件把初始化、resize、setValue、getValue、destroy 全部收敛到组件内部业务侧只暴露取值赋值两个接口。这样后续不管遇到弹窗、Tab、路由切换还是表单联动所有问题都有一个统一的处理入口。我在几个项目里都是这么干的后期维护和排查问题的成本差出好几倍。