diff --git a/.vscode/settings.json b/.vscode/settings.json index 1b318ab8..6435548d 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -54,9 +54,8 @@ "typescript.tsdk": "node_modules/typescript/lib", "alias-skip.mappings": { "@": "/src", - "@use-utils": "/src/utils", - "@use-api": "/src/axios/api", - "@use-images": "/src/assets/images", + "@api": "/src/api", + "@images": "/src/assets/images", "@mock": "/mock" }, "alias-skip.allowedsuffix": ["ts", "tsx"], diff --git a/docs/ai-development.md b/docs/ai-development.md index d7504129..567d259c 100644 --- a/docs/ai-development.md +++ b/docs/ai-development.md @@ -26,7 +26,7 @@ Codex 自动读取根目录 `AGENTS.md`;Cursor、Copilot 和 Claude 的项目 | 命令 | 用途与结果 | | ------------------------------------------------------- | -------------------------------------------------------------------- | | `pnpm env:check` | 检查 Node、pnpm 和依赖安装状态,失败时返回非零退出码并提示修复方式 | -| `pnpm typecheck` | 检查应用、测试和 Vite 配置类型,不输出构建文件 | +| `pnpm typecheck` | 检查应用、测试、Node 构建配置和 Mock 类型,不生成 JS 或声明文件 | | `pnpm lint` | 检查代码与 Vue 规则,不改文件;warning 也会失败 | | `pnpm format:check` | 检查格式,不改文件 | | `pnpm lint:fix` | 显式自动修复可修复的代码规范问题 | @@ -43,6 +43,20 @@ Codex 自动读取根目录 `AGENTS.md`;Cursor、Copilot 和 Claude 的项目 命令不接收业务参数;Vite/Vitest 参数使用对应 CLI 选项。日志来自各工具,退出码 `0` 表示本项检查通过。`pnpm check` 的生产产物写入 `dist/production`,需要保留源码之外的临时证据时放入 `.ai-local/`。 +## TypeScript 项目配置 + +根目录的 [tsconfig.json](../tsconfig.json) 用项目引用组织三个检查单元。严格模式、模块解析和 TypeScript 路径别名集中在 [tsconfig.base.json](../tsconfig.base.json)。Vite 的运行时别名在 `vite.custom.config.ts`,更改别名时同步更新两处。 + +| 配置 | 检查范围 | 环境 | +| ------------------------------------------- | -------------------------------------------------- | ----------------------------------------------- | +| [tsconfig.app.json](../tsconfig.app.json) | `src` 和自动生成的 Vue 声明 | 浏览器、Vue JSX 和 Vite 客户端 | +| [tsconfig.node.json](../tsconfig.node.json) | Vite、Vitest、UnoCSS 配置,`vite-helper` 和 `mock` | Node.js | +| [tsconfig.test.json](../tsconfig.test.json) | `__test__` 及测试所引用的源码 | 应用类型、Happy DOM、Node.js 和 Vitest 全局类型 | + +项目的 `types` 列表控制自动加载的环境声明。依赖也能通过自身声明引入其他类型,例如 `vite-svg-loader` 的声明引用 Vite 的 Node 类型。 + +`pnpm typecheck` 通过 `vue-tsc --build` 检查全部项目,增量缓存存放在 `.ai-local/`。需要从头检查时运行 `pnpm exec vue-tsc --build --force`。单独检查应用或测试可用 `pnpm exec vue-tsc -p tsconfig.app.json` 或 `pnpm exec vue-tsc -p tsconfig.test.json`,Node 配置可用 `pnpm exec tsc -p tsconfig.node.json`。VS Code 应通过工作区的 TypeScript 版本读取这些配置。 + ## 给 AI 的任务示例 ```text diff --git a/docs/toolchain-upgrade.md b/docs/toolchain-upgrade.md index 093b824d..3a45eb68 100644 --- a/docs/toolchain-upgrade.md +++ b/docs/toolchain-upgrade.md @@ -136,6 +136,14 @@ Pinia 设置沿用原持久化 key,旧裸 Logo 名称在读取时迁移;锁 公共 chunk 大小、ContentWrapper 静态/动态导入与 Mock CORS 序列化提示仍保留,未降低检查严格度或调高告警门槛。 +## 2026-11-03 TypeScript 项目配置拆分 + +旧配置只在 `vue-tsc` 命令行传入 `--noEmit`。直接读取项目配置时,`allowImportingTsExtensions` 会触发 TS5096。现在共享配置声明 `noEmit`,由根项目分别引用应用、Node 与测试配置。Vue JSX 和自动导入声明由应用及测试配置加载。TypeScript 6 的 `DOM` 已包含可迭代声明,Vite 继续通过 `build.sourcemap` 控制开发和生产的 sourcemap。 + +依赖与锁文件沿用当前版本。完整命令和项目归属见 [TypeScript 项目配置](ai-development.md#typescript-项目配置)。 + +在 Node.js 26.13.0 与 pnpm 12.16.1 下,`pnpm check` 通过类型、ESLint、Prettier、59 个测试文件的 240 个用例和生产构建。`pnpm dev-build` 通过,并生成开发版 JS sourcemap。通过 TypeScript 服务核对了应用入口、Vite 配置、Mock 文件和测试文件各自使用的项目。 + ## 参考资料 - [Node.js 26.13.0 LTS](https://nodejs.org/en/blog/release/v26.13.0) diff --git a/package.json b/package.json index d7a1484b..71377efb 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,7 @@ "dev": "pnpm icons:generate && vite", "icons:generate": "node scripts/icons.mjs", "icons:check": "node scripts/icons.mjs --check", - "typecheck": "pnpm icons:check && vue-tsc --noEmit", + "typecheck": "pnpm icons:check && vue-tsc --build", "build": "pnpm icons:generate && pnpm typecheck && vite build", "preview": "vite preview", "dev-build": "pnpm icons:generate && pnpm typecheck && vite build --mode development", diff --git a/src/app-config/app-config.ts b/src/app-config/app-config.ts index 4b157cba..7a7085f6 100644 --- a/src/app-config/app-config.ts +++ b/src/app-config/app-config.ts @@ -1,4 +1,5 @@ -import type { AppMenuConfig, PreloadingConfig } from '@/types' +import type { AppMenuConfig } from '@/types/modules/app-config' +import type { PreloadingConfig } from '@/types/modules/vite-custom-config' import type { MessageProviderProps } from 'naive-ui' /** diff --git a/src/app-config/design-config.ts b/src/app-config/design-config.ts index cba52183..afa79334 100644 --- a/src/app-config/design-config.ts +++ b/src/app-config/design-config.ts @@ -1,4 +1,4 @@ -import type { AppTheme } from '@/types' +import type { AppTheme } from '@/types/modules/vite-custom-config' /** 明暗主题共用的菜单尺寸与前景色配置。 */ const menuThemeOverrides = { diff --git a/src/types/modules/vite-custom-config.ts b/src/types/modules/vite-custom-config.ts index 296c97aa..0af01f1c 100644 --- a/src/types/modules/vite-custom-config.ts +++ b/src/types/modules/vite-custom-config.ts @@ -1,5 +1,4 @@ -import type { IconName } from '@/icons' -import type { Recordable } from '@/types' +import type { IconName } from '@/icons/manifest' import type { GlobalThemeOverrides } from 'naive-ui' import type { AliasOptions, @@ -8,6 +7,7 @@ import type { UserConfigExport, } from 'vite' import type { VNode, VNodeChild } from 'vue' +import type { Recordable } from './helper' export interface LayoutSideBarLogo { icon?: IconName | VNode diff --git a/tsconfig.app.json b/tsconfig.app.json new file mode 100644 index 00000000..7827b3fc --- /dev/null +++ b/tsconfig.app.json @@ -0,0 +1,11 @@ +{ + "extends": "./tsconfig.base.json", + "compilerOptions": { + "lib": ["ESNext", "DOM"], + "jsx": "preserve", + "jsxImportSource": "vue", + "types": ["vite/client", "naive-ui/volar"], + "tsBuildInfoFile": "./.ai-local/tsconfig.app.tsbuildinfo" + }, + "include": ["src/**/*", "unplugin/*.d.ts"] +} diff --git a/tsconfig.base.json b/tsconfig.base.json new file mode 100644 index 00000000..0d186c92 --- /dev/null +++ b/tsconfig.base.json @@ -0,0 +1,27 @@ +{ + "compilerOptions": { + "target": "ESNext", + "useDefineForClassFields": true, + "module": "ESNext", + "moduleResolution": "Bundler", + "strict": true, + "newLine": "LF", + "noEmit": true, + "incremental": true, + "resolveJsonModule": true, + "isolatedModules": true, + "allowImportingTsExtensions": true, + "esModuleInterop": true, + "skipLibCheck": true, + "paths": { + "@": ["./src"], + "@/*": ["./src/*"], + "@api": ["./src/api"], + "@api/*": ["./src/api/*"], + "@images": ["./src/assets/images"], + "@images/*": ["./src/assets/images/*"], + "@mock": ["./mock"], + "@mock/*": ["./mock/*"] + } + } +} diff --git a/tsconfig.json b/tsconfig.json index 8e830e88..01490aab 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,39 +1,8 @@ { - "compilerOptions": { - "target": "ESNext", - "useDefineForClassFields": true, - "module": "ESNext", - "moduleResolution": "bundler", - "strict": true, - "newLine": "LF", - "jsx": "preserve", - "sourceMap": true, - "resolveJsonModule": true, - "isolatedModules": true, - "allowImportingTsExtensions": true, - "esModuleInterop": true, - "lib": ["ESNext", "DOM", "DOM.Iterable"], - "skipLibCheck": true, - "jsxImportSource": "vue", - "paths": { - "@": ["./src"], - "@/*": ["./src/*"], - "@api": ["./src/api"], - "@api/*": ["./src/api/*"], - "@images": ["./src/assets/images"], - "@images/*": ["./src/assets/images/*"], - "@mock/*": ["./mock/*"], - "@mock": ["./mock"] - }, - "types": ["node", "vite/client", "vitest/globals", "naive-ui/volar"] - }, - "include": [ - "*.config.ts", - "vite-helper/**/*.ts", - "package.json", - "./unplugin/**/*", - "src/**/*", - "mock/**/*", - "__test__/**/*" + "files": [], + "references": [ + { "path": "./tsconfig.app.json" }, + { "path": "./tsconfig.node.json" }, + { "path": "./tsconfig.test.json" } ] } diff --git a/tsconfig.node.json b/tsconfig.node.json new file mode 100644 index 00000000..4c4973b7 --- /dev/null +++ b/tsconfig.node.json @@ -0,0 +1,9 @@ +{ + "extends": "./tsconfig.base.json", + "compilerOptions": { + "lib": ["ESNext"], + "types": ["node"], + "tsBuildInfoFile": "./.ai-local/tsconfig.node.tsbuildinfo" + }, + "include": ["*.config.ts", "vite-helper/**/*.ts", "mock/**/*.ts"] +} diff --git a/tsconfig.test.json b/tsconfig.test.json new file mode 100644 index 00000000..becada85 --- /dev/null +++ b/tsconfig.test.json @@ -0,0 +1,8 @@ +{ + "extends": "./tsconfig.app.json", + "compilerOptions": { + "types": ["vite/client", "naive-ui/volar", "node", "vitest/globals"], + "tsBuildInfoFile": "./.ai-local/tsconfig.test.tsbuildinfo" + }, + "include": ["__test__/**/*", "src/**/*.d.ts", "unplugin/*.d.ts"] +} diff --git a/vite.custom.config.ts b/vite.custom.config.ts index 2994e39b..7767d03c 100644 --- a/vite.custom.config.ts +++ b/vite.custom.config.ts @@ -1,5 +1,5 @@ import { fileURLToPath, URL } from 'node:url' -import type { AppConfigExport } from '@/types' +import type { AppConfigExport } from '@/types/modules/vite-custom-config' import type { BuildOptions } from 'vite' import { PRE_LOADING_CONFIG } from './src/app-config/app-config.ts' import { APP_THEME } from './src/app-config/design-config.ts'