TypeScript 5.x结合ES Decorators时Quokka.js无法正常运行的问题

问题场景 #

我在VSCode中使用Quokka.js运行包含ES标准Decorators的TypeScript文件，相关代码及配置如下：

装饰器定义代码 #

function message<Input extends new (...args: any) => any>(msg: string) {
    return function (value: Input, context: ClassDecoratorContext) {
        // 剩余代码省略...
    };
}

消费类代码 #

@message("Hello from the employee class")
export class Employee {
    public firstName: string;
    // 剩余代码省略...
}

问题现象 #

• 代码可通过tsc命令正常转译，转译后的.js文件能在Quokka.js中正常运行
• 直接运行TypeScript原文件时触发语法错误：

Quokka 'Decorators.ts' (node: v18.16.0, TypeScript: v5.3.3)
Failed to instrument scripts/typescript/Advanced/Decorators.js
49 | @message("Hello from the employee class")
| ^ SyntaxError: Unexpected character '@' (49:4)

已完成的配置 #

1. 在package.json中配置Quokka使用本地TypeScript 5.3.3并禁用SWC：

"quokka": { 
    "ts": {
      "compiler": "typescript",
      "swc": false
    }
  }

2. 因TypeScript 5.x使用标准Decorators无需启用旧版实验性配置，tsconfig.json中注释了相关选项：

// "experimentalDecorators": true,
// "emitDecoratorMetadata": true, 

解决方案 #

1. 修正tsconfig.json的标准装饰器支持配置 #

TypeScript 5.x的标准Decorators需要明确的环境配置，确保tsconfig.json包含以下设置：

{
  "compilerOptions": {
    "target": "ES2022", // 标准装饰器需要ES2022+语法支持
    "module": "ESNext", // 或匹配你的运行环境的模块规范
    "useDefineForClassFields": true, // TS5.x默认开启，显式声明避免歧义
    // 其他原有配置...
  }
}

2. 让Quokka.js明确加载项目的tsconfig #

Quokka可能未自动读取根目录的tsconfig，需在package.json的Quokka配置中指定路径：

"quokka": { 
    "ts": {
      "compiler": "typescript",
      "swc": false,
      "tsconfig": "./tsconfig.json" // 显式指定tsconfig路径
    }
  }

3. 验证Quokka使用的TypeScript版本 #

执行npm ls typescript确认本地已安装5.3.3版本，若Quokka仍使用全局版本，可在VSCode的Quokka扩展设置中强制指定本地TypeScript的路径。

4. 重启配置生效 #

关闭当前Quokka会话，重启VSCode后重新启动Quokka运行TypeScript文件，确保所有配置变更生效。

内容的提问来源于stack exchange，提问作者atconway