企业官网建设流程全解析

Quasar App (Vite) 代码检查与格式化完整指南：Oxlint + Oxfmt 与 ESLint + Prettier 双方案实战

【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar

Quasar 应用脚手架（@quasar/app-vite）在创建项目时即可选择内置 ESLint（可搭配 Prettier 格式化器），同时新一代基于 Rust 的 Oxc 生态工具（Oxlint 与 Oxfmt）也已作为官方推荐的极速方案被写入脚手架模板。本指南基于@quasar/app-vite仓库的官方文档、脚手架模板与@quasar/app-vite/eslint导出实现，完整讲解两套方案从依赖安装、配置文件编写、VSCode 集成到 lint 规则定制的全部细节，读完即可为你的 Quasar 项目落地一套可复制、可运行的代码质量工作流。

Oxlint + Oxfmt：Rust 极速方案的完整落地

Oxlint 与 TS 版oxlint.config.ts即与该章节给出的配置一一对应。

依赖安装：JS 与 TS 项目差异

JS 项目只需安装两个包：

# PNPM pnpm add -D oxlint oxfmt # Yarn yarn add -D oxlint oxfmt # NPM npm install -D oxlint oxfmt # Bun bun add -D oxlint oxfmt

TypeScript 项目需要额外补充类型检查与类型感知规则所需的能力，共五个包：

# PNPM pnpm add -D oxlint oxfmt oxlint-tsgolint typescript vue-tsc # Yarn yarn add -D oxlint oxfmt oxlint-tsgolint typescript vue-tsc # NPM npm install -D oxlint oxfmt oxlint-tsgolint typescript vue-tsc # Bun bun add -D oxlint oxfmt oxlint-tsgolint typescript vue-tsc

其中oxlint-tsgolint用于在 lint 时接入 TypeScript 语义（类型感知规则），vue-tsc负责 Vue 单文件组件的类型检查（见下文typecheck脚本），typescript是前两者的基础依赖。

package.json 脚本设计

"scripts": { "lint": "oxfmt && oxlint --fix", "lint:check": "oxfmt --check && oxlint", "typecheck": "vue-tsc --noEmit" }

• lint：先由oxfmt直接重写文件完成格式化，再由oxlint --fix执行自动修复，一次命令完成“格式化 + 修复 + 检查”全流程；
• lint:check：只做校验不做修改，oxfmt --check会以非零退出码报告存在格式差异的文件，适合接入 CI；
• typecheck：vue-tsc --noEmit对.vue与.ts做类型检查，仅 TypeScript 项目需要。

配置文件：JS 用 JSON，TS 用 defineConfig

JS 项目创建/.oxlintrc.json：

{ "$schema": "./node_modules/oxlint/configuration_schema.json", "ignorePatterns": [ "**/node_modules/", "dist/", "quasar.config.*.temporary.compiled*", ".quasar/", "src-cordova/", "src-capacitor/" ], "options": { "maxWarnings": 10 }, "plugins": ["vue", "import", "eslint", "promise", "unicorn"], "categories": { "correctness": "error" // "style": "error", // "pedantic": "warn", // "suspicious": "error", // "perf": "error", // "restriction": "error" }, "rules": {}, "env": { "builtin": true } }

TS 项目创建/oxlint.config.ts，使用defineConfig获得类型提示，并在options中额外开启类型感知能力：

import { defineConfig } from 'oxlint' export default defineConfig({ $schema: './node_modules/oxlint/configuration_schema.json', ignorePatterns: [ '**/node_modules/', 'dist/', 'quasar.config.*.temporary.compiled*', '.quasar/', 'src-cordova/', 'src-capacitor/' ], options: { typeAware: true, typeCheck: true, maxWarnings: 10 }, plugins: ['typescript', 'vue', 'import', 'eslint', 'promise', 'unicorn'], categories: { correctness: 'error' }, rules: {}, env: { builtin: true } })

几点值得展开的配置含义：

• ignorePatterns：五个忽略项与 Quasar 项目结构强绑定——dist/是构建产物、.quasar/是 Quasar 运行时临时文件、quasar.config.*.temporary.compiled*是配置文件编译中间产物、src-cordova/与src-capacitor/是移动端原生工程目录。注意模板里的 TS 版还额外忽略了src/router/typed-router.d.ts（路由类型自动生成文件，见 TS 模板）；
• options.maxWarnings：允许最多 10 个 warning，超过则命令以失败退出，给团队留出渐进治理的缓冲空间；
• options.typeAware / typeCheck（TS 专属）：开启后 oxlint 借助oxlint-tsgolint提供基于类型信息的规则（如no-unnecessary-type-assertion一类），代价是需要读取 tsconfig；
• categories：oxlint 把规则按类别（correctness / suspicious / style / pedantic / perf / restriction）组织，可整体开关。默认仅将correctness提升为 error，其余按需取消注释启用，示例中pedantic: 'warn'适合想进一步收紧代码风格的团队；
• env.builtin：内置全局变量（console、window等）直接可用，避免误报未定义。

oxfmt 格式化配置

oxfmt 的配置风格与 Prettier 高度相似，便于老项目平滑迁移。JS 项目创建/.oxfmtrc.json：

{ "$schema": "./node_modules/oxfmt/configuration_schema.json", "ignorePatterns": [ "**/node_modules/", "dist/", "quasar.config.*.temporary.compiled*", ".quasar/", "src-cordova/", "src-capacitor/" ], "printWidth": 80, "arrowParens": "avoid", "bracketSpacing": true, "bracketSameLine": false, "htmlWhitespaceSensitivity": "strict", "semi": false, "singleQuote": true, "quoteProps": "as-needed", "trailingComma": "none", "useTabs": false, "vueIndentScriptAndStyle": false }

TS 项目创建/oxfmt.config.ts，默认风格略有差异（分号、引号风格与 JS 版相反，体现两套模板的默认取向）：

import { defineConfig } from 'oxfmt' export default defineConfig({ $schema: './node_modules/oxfmt/configuration_schema.json', ignorePatterns: [ '**/node_modules/', 'dist/', 'quasar.config.*.temporary.compiled*', '.quasar/', 'src-cordova/', 'src-capacitor/' ], printWidth: 80, arrowParens: 'avoid', bracketSpacing: true, bracketSameLine: false, htmlWhitespaceSensitivity: 'strict', semi: true, singleQuote: false, quoteProps: 'as-needed', trailingComma: 'none', useTabs: false, vueIndentScriptAndStyle: false })

这些选项对应关系：printWidth换行宽度（80 是社区主流取值）；arrowParens: 'avoid'单参数箭头函数省略括号；semi是否加分号；singleQuote是否用单引号；trailingComma: 'none'不添加尾逗号；vueIndentScriptAndStyle控制<script>/<style>块内容是否随标签缩进。可按团队规范自行调整。

VSCode 集成：安装 Oxc 扩展并接管保存动作

创建/.vscode/settings.json，让编辑器在保存时自动格式化并执行 oxlint 自动修复。JS 项目：

{ "editor.codeActionsOnSave": { "source.fixAll.oxc": "always" }, "oxc.fmt.configPath": ".oxfmtrc.json", "editor.defaultFormatter": "oxc.oxc-vscode", "editor.formatOnSave": true }

TS 项目只需把oxc.fmt.configPath指向oxfmt.config.ts：

{ "editor.codeActionsOnSave": { "source.fixAll.oxc": "always" }, "oxc.fmt.configPath": "oxfmt.config.ts", "editor.defaultFormatter": "oxc.oxc-vscode", "editor.formatOnSave": true }

三个关键点：

• editor.defaultFormatter设为oxc.oxc-vscode，确保格式化器是 Oxc 而非 Prettier，避免两套格式化规则互相覆盖；
• source.fixAll.oxc对应 Oxc 扩展暴露的 code action，保存时触发 oxlint 的自动修复（等价于oxlint --fix）；
• oxc.fmt.configPath显式指向项目格式化配置文件，防止扩展使用默认风格。

同时在/.vscode/extensions.json中推荐团队成员安装扩展：

{ "recommendations": ["oxc.oxc-vscode"] }

这与 Quasar 脚手架模板的 extensions.json 结构一致（脚手架在 oxlint 预设下同样推荐oxc.oxc-vscode，在 eslint 预设下则推荐dbaeumer.vscode-eslint与esbenp.prettier-vscode）。

ESLint + Prettier：经典方案深度配置

拥有一个代码检查器（如 ESLint v9+）非常有必要，它保证代码可读性，还能在代码真正运行前就捕获一部分错误。当你用create-quasar脚手架创建项目时，CLI 会询问是否启用 ESLint（以及是否搭配 Prettier 作为格式化器），选中的结果会直接写入模板，见 JS ESLint 模板 与 TS ESLint 模板。

JS 项目：依赖、构建配置与规则文件

第一步，安装依赖：

# PNPM pnpm add -D @eslint/js eslint@10 eslint-plugin-vue vue-eslint-parser globals vite-plugin-checker # Yarn yarn add -D @eslint/js eslint@10 eslint-plugin-vue vue-eslint-parser globals vite-plugin-checker # NPM npm install -D @eslint/js eslint@10 eslint-plugin-vue vue-eslint-parser globals vite-plugin-checker # Bun bun add -D @eslint/js eslint@10 eslint-plugin-vue vue-eslint-parser globals vite-plugin-checker

若同时需要 Prettier 格式化，再安装：

pnpm add -D prettier@3 @vue/eslint-config-prettier

各依赖职责：@eslint/js提供 JS 推荐规则集（js.configs.recommended）；eslint@10是 flat config 时代的 ESLint 主程序；eslint-plugin-vue提供 Vue 单文件组件规则（flat/essential等预设）；vue-eslint-parser负责解析.vue的<script>块；globals提供浏览器/Node/Service Worker 等环境的全局变量声明；vite-plugin-checker把类型检查与 lint 结果以 overlay 形式注入 Vite 开发服务器；@vue/eslint-config-prettier的skip-formatting子路径用于关闭与 Prettier 冲突的格式类规则。

第二步，在quasar.config.js中接入 vite-plugin-checker：

build: { vitePlugins: [ [ 'vite-plugin-checker', { eslint: { lintCommand: 'eslint -c ./eslint.config.js "./src*/**/*.{js,mjs,cjs,vue}"', useFlatConfig: true } }, { server: false } ] ] }

要点：lintCommand指定检查的 glob（覆盖src、src-pwa、src-ssr、src-ssg、src-bex等 Quasar 约定目录下的 JS/MJS/CJS/Vue 文件）；useFlatConfig: true声明使用 ESLint 9+ 的 flat config；{ server: false }表示仅在构建阶段运行，避免拖慢 dev server 启动（该插件机制同@quasar/app-vite的 vitePlugins 规范，属于 Quasar 官方构建管线的一部分）。

第三步，编写/eslint.config.js：

import js from '@eslint/js' import globals from 'globals' import pluginVue from 'eslint-plugin-vue' import pluginQuasar from '@quasar/app-vite/eslint' // the following is optional, if you want prettier too: import prettierSkipFormatting from '@vue/eslint-config-prettier/skip-formatting' export default [ { /** * Ignore the following files. * Please note that pluginQuasar.configs.recommended() already ignores * the "node_modules" folder for you (and all other Quasar project * relevant folders and files). * * ESLint requires "ignores" key to be the only one in this object */ // ignores: [] }, ...pluginQuasar.configs.recommended(), js.configs.recommended, /** * pluginVue.configs.base * -> Settings and rules to enable correct ESLint parsing. * pluginVue.configs['flat/essential'] * -> base, plus rules to prevent errors or unintended behavior. * pluginVue.configs["flat/strongly-recommended"] * -> Above, plus rules to considerably improve code readability and/or dev experience. * pluginVue.configs["flat/recommended"] * -> Above, plus rules to enforce subjective community defaults to ensure consistency. */ ...pluginVue.configs['flat/essential'], { languageOptions: { ecmaVersion: 'latest', sourceType: 'module', globals: { ...globals.browser, ...globals.node, // SSR, SSG, Electron, config files ga: 'readonly', // Google Analytics cordova: 'readonly', Capacitor: 'readonly', chrome: 'readonly', // BEX related browser: 'readonly' // BEX related } }, // add your custom rules here rules: { 'prefer-promise-reject-errors': 'off', // slots use the "#" shorthand everywhere, as in the Quasar docs 'vue/v-slot-style': ['warn', 'shorthand'], // allow debugger during development only 'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off' } }, { files: ['src-pwa/sw/**/*.js'], languageOptions: { globals: { ...globals.serviceworker } } }, prettierSkipFormatting // optional, if you want prettier ]

这份配置中值得重点解释的部分：

• pluginQuasar.configs.recommended()：这是@quasar/app-vite包导出的官方 ESLint 共享配置（源码见 eslint.js，CJS 版见 eslint.cjs），通过package.json的"./eslint"导出子路径暴露。其实现非常轻量——recommended()返回[{ ignores: ignoreList }]，把dist/*、src-capacitor/*、src-cordova/*、.quasar/*、quasar.config.*.temporary.compiled*全部加入 ignores（这正是后文“自动忽略清单”的代码出处），因此你不必手动忽略这些目录；
• 全局变量：合并了globals.browser与globals.node，因为 Quasar 单代码库要同时面向 SPA（浏览器）、SSR/SSG（Node）、Electron（主进程/预加载）、BEX（chrome/browser）与移动端（cordova/Capacitor）运行，未声明这些全局会导致误报no-undef；
• 内置规则：prefer-promise-reject-errors: 'off'是 Quasar 官方推荐关闭项；vue/v-slot-style: ['warn', 'shorthand']与 Quasar 文档一致强制#简写插槽；no-debugger在生产构建中升级为 error、开发环境放行；
• Service Worker 专项：为src-pwa/sw/**/*.js单独注入globals.serviceworker，否则 sw.js 里的self、caches等会报未定义。

TS 项目：类型感知规则与 vue-tsc 检查

第一步，安装依赖：

pnpm add -D vue-tsc @vue/eslint-config-typescript @eslint/js eslint@10 eslint-plugin-vue globals vite-plugin-checker

Prettier 附加依赖同 JS 项目：

pnpm add -D prettier@3 @vue/eslint-config-prettier

第二步，quasar.config.js设置：与 JS 版基本一致，仅两处差异——启用vueTsc: true让 vite-plugin-checker 同时跑 Vue 类型检查，且 lintCommand 的 glob 扩展为包含.ts：

build: { vitePlugins: [ [ 'vite-plugin-checker', { vueTsc: true, eslint: { lintCommand: 'eslint -c ./eslint.config.js "./src*/**/*.{ts,js,mjs,cjs,vue}"', useFlatConfig: true } }, { server: false } ] ] }

第三步，/eslint.config.js：用defineConfigWithVueTs包裹，并叠加vueTsConfigs.recommendedTypeChecked启用基于类型信息的规则：

import js from '@eslint/js' import globals from 'globals' import pluginVue from 'eslint-plugin-vue' import pluginQuasar from '@quasar/app-vite/eslint' import { defineConfigWithVueTs, vueTsConfigs } from '@vue/eslint-config-typescript' // the following is optional, if you want prettier too: import prettierSkipFormatting from '@vue/eslint-config-prettier/skip-formatting' export default defineConfigWithVueTs( { // ignores: [] }, pluginQuasar.configs.recommended(), js.configs.recommended, pluginVue.configs['flat/essential'], { files: ['**/*.ts', '**/*.vue'], rules: { '@typescript-eslint/consistent-type-imports': [ 'error', { prefer: 'type-imports' } ] } }, vueTsConfigs.recommendedTypeChecked, { languageOptions: { ecmaVersion: 'latest', sourceType: 'module', globals: { ...globals.browser, ...globals.node, // SSR, SSG, Electron, config files process: 'readonly', // process.env.* ga: 'readonly', // Google Analytics cordova: 'readonly', Capacitor: 'readonly', chrome: 'readonly', // BEX related browser: 'readonly' // BEX related } }, rules: { 'prefer-promise-reject-errors': 'off', 'vue/v-slot-style': ['warn', 'shorthand'], 'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off' } }, { files: ['src-pwa/sw/**/*.ts'], languageOptions: { globals: { ...globals.serviceworker } } }, prettierSkipFormatting // optional, if you want prettier )

TS 版与 JS 版的关键差异：

• defineConfigWithVueTs+vueTsConfigs.recommendedTypeChecked：前者提供 Vue 单文件组件与 TS 类型系统协同的配置工厂，后者开启recommended-type-checked级别规则（如no-floating-promises、no-unsafe-argument等），这些规则需要 parser 服务与项目类型信息，也因此必须在全局变量中加入process: 'readonly'（否则process.env.NODE_ENV在使用类型检查规则时报未定义）；
• consistent-type-imports：强制import type { Foo }风格的类型导入，配合verbatimModuleSyntax类编译设置可彻底消除类型导入的运行时残留；
• Service Worker 段按src-pwa/sw/**/*.ts匹配 TS 文件。

性能优化：务必忽略无关文件

[!WARNING] 请务必忽略未使用的文件以提升性能。若对未使用的文件/文件夹执行 lint，开发体验会显著下降。

自定义忽略只需编辑/eslint.config.js中第一个对象的ignores数组：

export default [ { /** * Ignore the following files. * Please note that pluginQuasar.configs.recommended() already ignores * the "node_modules" folder for you (and all other Quasar project * relevant folders and files). * * ESLint requires "ignores" key to be the only one in this object */ ignores: [] // <<<---- here! },

需要注意的是，pluginQuasar.configs.recommended()会自动向 ESLint 的ignores注入以下清单（无需重复添加）：

// not an exhaustive list auto-added to "ignores" ;[ 'dist/*', 'src-capacitor/*', 'src-cordova/*', '.quasar/*', 'quasar.config.*.temporary.compiled*' ]

这与我们前面读到的 eslint.js 中ignoreList常量完全一致：dist构建产物、src-capacitor/src-cordova原生工程、.quasar运行时临时目录、quasar.config.*.temporary.compiled*配置编译中间文件都不应进入 lint 范围。另注意 flat config 的一个硬性约束：含ignores键的配置对象中不能出现其他键（注释中已强调“ESLint requires 'ignores' key to be the only one in this object”），因此忽略清单必须独占一个数组元素。

自定义 lint 规则

规则可以被删除、修改或新增。注意两点：

• 部分规则是标准 ESLint 规则，例如brace-style；
• 部分规则来自 eslint-plugin-vue，例如vue/max-attributes-per-line。

调整规则的入口有两个：标准规则查阅 ESLint 官方规则文档（eslint.org/docs/rules），Vue 专属规则查阅 eslint-plugin-vue 规则文档（eslint.vuejs.org/rules），然后将规则写入rules: {}块即可，如本指南前面示例中的vue/v-slot-style、no-debugger与@typescript-eslint/consistent-type-imports。

两套方案如何选择

结合文档与仓库实际模板可以给出如下参考：

@quasar/app-vite（当前仓库版本 3.8.4）同时支持两条路径：脚手架 ESLint 模板 与 oxlint 模板 并存，create-quasar创建项目时按你的选择生成对应文件；官方 ESLint 共享忽略配置则由 app-vite/exports/eslint/ 统一维护，保证所有 Quasar 项目忽略清单行为一致。

实践建议：追求极速反馈、新项目从零开始，优先选 Oxlint + Oxfmt（配合 VSCode Oxc 扩展体验最佳）；需要最丰富的规则生态、团队已有大量 ESLint 规则沉淀，或依赖第三方 ESLint 插件（如安全、可访问性类），则选 ESLint + Prettier，并按上文接入vite-plugin-checker获得构建期检查。无论哪套方案，都请保持quasar.config.*.temporary.compiled*、.quasar/、dist/等 Quasar 专属目录始终处于忽略清单中，这是保证检查速度与结果准确的前提。

【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar