Lit Playground下载代码本地运行npm run serve无显示问题排查

页面空白是三类配置错误叠加导致的：

• 替换后的package.json里，web-dev-server默认启动参数没有开启TS文件自动转译能力，浏览器无法直接识别TS语法、也无法解析npm依赖的裸模块导入路径，脚本加载阶段就直接失败，页面不会渲染任何内容。
• Lit组件基于装饰器语法实现，自定义添加的tsconfig.json如果没有开启对应编译配置，转译后的代码会出现语法报错，阻断组件渲染。
• 配置调整过程中如果误改了index.html里的脚本引入规则，比如漏写type="module"属性、写错TS文件的相对路径，也会导致资源加载失败。

按以下顺序调整配置即可正常运行：

1. 修正web-dev-server启动参数
   打开package.json，找到scripts字段下的serve命令，替换为以下配置：

"serve": "wds --node-resolve --open --watch --esbuild-target auto --app-index index.html"

参数说明：--node-resolve用于处理npm依赖的裸模块导入，--esbuild-target auto会让服务自动转译TS/JS新语法到当前浏览器兼容版本，不需要额外跑独立的TS构建流程。

2. 替换为Lit项目最小可用TS配置
   打开你自己添加的tsconfig.json，覆盖为以下配置：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "experimentalDecorators": true,
    "useDefineForClassFields": false,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true
  },
  "include": ["*.ts"]
}

重点注意必须开启experimentalDecorators、将useDefineForClassFields设为false，这两个配置是Lit装饰器语法正常运行的必要条件，也是之前遇到TS报错的核心原因。

3. 核对index.html的脚本引入
   打开index.html，确认组件脚本的引入标签符合以下格式，路径和文件名和本地实际文件一致：

<script type="module" src="./my-timer.ts"></script>

必须携带type="module"属性，否则浏览器会把ES模块格式的脚本当普通JS解析，直接报语法错误。

4. 清理缓存重启服务
   在项目根目录执行以下命令，清除旧的依赖缓存后重新安装、启动服务：

# 删除旧依赖和锁文件
rm -rf node_modules package-lock.json
# 重新安装依赖
npm install
# 启动开发服务
npm run serve

服务启动后会自动打开浏览器页面，此时my-timer组件就能正常渲染、交互。

• 不需要额外安装第三方TS转译插件，新版本web-dev-server自带的esbuild转译能力完全足够运行Lit示例项目，多余插件反而容易引发版本冲突导致转译失败。
• 如果启动后打开浏览器控制台看到404报错，优先核对报错资源的文件名大小写、相对路径是否正确，本地开发环境的路径校验是大小写敏感的。
• 如果控制台报装饰器相关语法错误，优先核对tsconfig里的两个装饰器相关配置是否和上述给出的一致，绝大多数TS相关报错都是这两个配置写错导致的。

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