Astro项目构建报错：无法解析tsconfig的extends配置

问题描述 #

运行npm run build构建Astro项目，或执行npm run dev后访问Markdown页面时，抛出以下错误：

> astro-blog-template@0.0.1 build
> astro build

17:42:55 [build] output target: static   
17:42:55 [build] Collecting build info...
17:42:55 [build] Completed in 47ms.
17:42:55 [build] Building static entrypoints...
[vite:esbuild] failed to resolve "extends":"astro/tsconfigs/strict" in C:\Users\felix\documents\programmieren\hhh\tsconfig.json
file: C:/Users/felix/documents/programmieren/hhh/src/utils/getPostData.ts
 error   failed to resolve "extends":"astro/tsconfigs/strict" in C:\Users\felix\documents\programmieren\hhh\tsconfig.json
  File:
    C:/Users/felix/documents/programmieren/hhh/src/utils/getPostData.ts
  Stacktrace:
    at resolveExtends (file:///C:/Users/felix/Documents/Programmieren/hhh/node_modules/astro/node_modules/vite/dist/node/chunks/dep-5cb728cb.js:13162:9)    
    at parseExtends (file:///C:/Users/felix/Documents/Programmieren/hhh/node_modules/astro/node_modules/vite/dist/node/chunks/dep-5cb728cb.js:13135:34)     
    at parse$g (file:///C:/Users/felix/Documents/Programmieren/hhh/node_modules/astro/node_modules/vite/dist/node/chunks/dep-5cb728cb.js:13086:24)
    at async transformWithEsbuild (file:///C:/Users/felix/Documents/Programmieren/hhh/node_modules/astro/node_modules/vite/dist/node/chunks/dep-5cb728cb.js:13280:36)
    at async Object.transform (file:///C:/Users/felix/Documents/Programmieren/hhh/node_modules/astro/node_modules/vite/dist/node/chunks/dep-5cb728cb.js:13379:32)
    at async transform (file:///C:/Users/felix/Documents/Programmieren/hhh/node_modules/rollup/dist/es/shared/rollup.js:21911:16)
    at async ModuleLoader.addModuleSource (file:///C:/Users/felix/Documents/Programmieren/hhh/node_modules/rollup/dist/es/shared/rollup.js:22136:30)

尝试修改tsconfig.json配置（调整extends位置、添加include/exclude和路径别名）后，npm run dev偶尔能正常运行，但npm run build仍报错。

解决方案 #

1. 重新安装依赖 #

依赖安装不完整或缓存问题可能导致Astro内置的tsconfig文件缺失，执行以下步骤：

• 删除项目根目录下的node_modules文件夹和package-lock.json文件
• 运行npm install重新安装所有依赖

2. 更新Astro到稳定版本 #

旧版本Astro可能没有astro/tsconfigs/strict配置文件，或者路径存在兼容性问题：

• 运行npm update astro将Astro更新到最新稳定版

3. 修正tsconfig.json配置 #

核心问题：路径别名的baseUrl设置错误

原配置中baseUrl: "/"是系统根目录的绝对路径，而非项目根目录，导致TypeScript无法正确解析路径。将其改为相对路径./，同时简化配置排除干扰：

{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "types": ["astro/client"],
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "baseUrl": "./",
    "paths": {
      "@components/*": ["src/components/*"],
      "@layouts/*": ["src/layouts/*"]
    }
  },
  "include": ["src/**/*", "astro.config.mjs"],
  "exclude": ["node_modules"]
}

验证基础配置

如果上述修改后仍报错，可以先使用最简配置测试是否能正常构建：

{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "types": ["astro/client"]
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

确认基础配置可用后，再逐步添加路径别名等自定义配置。

4. 清理构建缓存 #

旧的构建缓存可能干扰新配置的解析：

• 运行npx astro clean清理Astro的构建缓存
• 重新执行npm run build测试

验证步骤 #

1. 执行npm run dev，确认开发服务启动正常且Markdown页面能正常访问
2. 执行npm run build，确认构建过程无报错，生成正确的静态文件

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