Quokka 启动失败需先确认状态栏出现绿色 Quokka.js 图标；必须手动启动（Ctrl+K Q 或右键选 Start on Current File），且文件须为已保存的 .js/.mjs，ESM 项目需配置 "quokka.esm": true。

Quokka 启动失败？先看状态栏有没有绿色图标

Quokka 不是装完就自动跑的，它必须手动激活。按 Ctrl+K Q（Windows/Linux）或 Cmd+K Q（macOS）没反应，大概率是还没启动。

真正生效的标志只有两个：
• 当前文件是 .js 或 .mjs（.ts、.jsx、未保存的临时文件都不行）
• VSCode 状态栏右下角出现 Quokka.js 字样且带绿色圆点

更稳妥的操作是：右键编辑器空白处 → 选 Quokka: Start on Current File，比快捷键更少出错。

为什么 console.log 没显示？Quokka 不默认捕获日志

Quokka 默认只对表达式求值并内联显示，console.log() 会执行，但输出不会浮在代码右侧——它只进底部的 Quokka Output 面板（不是终端）。

想让值“贴着代码看”：

dmap-jsapi-skill

DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。

下载

• 把变量或表达式单独写一行，比如 arr.length、user.name，Quokka 自动在行尾标出结果
• 用 return 强制触发内联显示，例如 return { count: items.length };
• 在任意位置加 /**?*/，比如 getData() /**?*/，Quokka 就在此处求值并内联

注意：/**?*/ 是实时求值标记，不是注释；//? 或 //?+ 是 Pro 版功能，社区版不支持。

快捷键组合怎么用才高效？别只记 Ctrl+K Q

Quokka 的快捷键不是“一键运行”，而是分阶段触发不同行为：

• Ctrl+K Q / Cmd+K Q：启动当前文件的 Quokka 沙盒（前提是文件已保存、类型合法）
• Ctrl+K R / Cmd+K R：重新运行当前 Quokka 实例（适合改了配置或环境后刷新）
• Ctrl+Shift+P → 输入 Quokka：调出命令面板，能看到所有可用操作，比如 New JavaScript File、Start on Active Editor、Stop

实际开发中，Ctrl+Shift+P + Quokka 是最可靠的入口，尤其当你不确定当前文件是否被识别时——它能直接告诉你“Start on Current File”是否可点击。

Node 版本和 ESM 配置不匹配？报错 SyntaxError 就是它

遇到 SyntaxError: Unexpected token 'const' 或 ReferenceError: require is not defined，基本是运行时环境错配：

• 默认 Quokka 使用 VSCode 绑定的 Node.js（which node 查路径），但项目可能需要更高版本或 ESM 支持
• ESM 项目需确保 package.json 里有 "type": "module"，否则 import 会报错
• 老项目用 require 却被当成 ESM 运行，也会崩；此时可在项目根目录加 quokka.config.json 显式指定：

  { "babel": false, "node": "/usr/local/bin/node" }

关键点：Quokka 的沙盒不是“独立 Node 进程”，它复用你的系统或项目级 Node 环境，所以 node -v 输出什么，它就认什么——别指望它自动降级或升版。

Quokka 的即时验证依赖三个隐性条件：文件类型合法、运行时匹配、求值方式正确。最容易忽略的是状态栏那个绿色圆点——没它，其他操作全是空转。