openEuler社区官网的代码规范：ESLint + StyleLint + Prettier的完美结合

openEuler社区官网的代码规范：ESLint + StyleLint + Prettier的完美结合

【免费下载链接】openEuler-portalThe repository of openEuler portal项目地址: https://gitcode.com/openeuler/openEuler-portal

前往项目官网免费下载：https://ar.openeuler.org/ar/

想要为开源社区贡献代码，却担心代码风格不一致？openEuler社区官网通过一套完整的代码规范工具链，让团队协作变得简单高效。本文将为您详细介绍openEuler官网如何通过ESLint、StyleLint和Prettier三大工具实现代码质量的完美控制，让您的开发体验更加顺畅！

为什么需要代码规范工具？

在大型开源项目中，代码一致性至关重要。openEuler社区官网作为一个由全球开发者共同维护的项目，面临着多开发者协作、代码风格统一、质量保障等挑战。通过ESLint、StyleLint和Prettier的组合，项目实现了：

• 自动化的代码质量检查：在提交前自动检测潜在问题
• 统一的代码风格：确保所有贡献者遵循相同的编码规范
• 提高开发效率：减少代码评审中的风格讨论时间
• 预防常见错误：通过静态分析避免运行时错误

ESLint：JavaScript/TypeScript代码的质量守护者

openEuler官网采用ESLint作为JavaScript和TypeScript代码的质量检查工具。配置文件位于项目根目录的eslint.config.js，采用了最新的Flat Config格式。

核心配置亮点

// 基础配置 import js from '@eslint/js'; import vue from 'eslint-plugin-vue'; import typescript from '@vue/eslint-config-typescript'; import prettierSkip from '@vue/eslint-config-prettier/skip-formatting';

项目配置了严格的TypeScript检查规则，禁止使用any类型（特殊情况需要注释说明原因），并要求所有未使用的变量必须显式处理。对于Vue 3组件，项目关闭了多单词组件名的限制，以适应项目实际情况。

自动修复功能

openEuler官网提供了便捷的修复命令：

pnpm fix # 自动修复ESLint可修复的问题

这个命令会自动修复大部分代码格式问题，让开发者专注于业务逻辑的实现。

StyleLint：CSS/SCSS样式的规范化管理

对于样式代码，openEuler官网使用StyleLint进行规范检查。配置文件位于app/stylelint.config.js，支持SCSS语法和Vue单文件组件。

样式规范的核心规则

项目采用了严格的样式编写规范：

1. CSS变量优先：必须使用OpenDesign提供的CSS变量，如var(--o-color-info1)、var(--o-spacing-h4)等
2. 响应式断点规范：使用respond-tomixin替代硬编码的媒体查询
3. BEM命名规范：采用block__element--modifier的命名约定
4. 禁止使用!important：通过提高选择器优先级解决样式冲突

自动修复样式问题

运行以下命令可以自动修复样式问题：

pnpm lint:style

这个命令会检查并修复所有Vue组件和SCSS文件中的样式问题。

Prettier：代码格式的自动化美化

Prettier作为代码格式化工具，确保所有代码保持一致的格式风格。配置文件位于.prettierrc.js，主要配置包括：

module.exports = { printWidth: 80, // 每行最大80字符 useTabs: false, // 使用空格而非制表符 singleQuote: true, // 使用单引号 tabWidth: 2, // 缩进为2个空格 semi: true, // 语句末尾添加分号 trailingComma: 'es5', // 在ES5中有效的尾随逗号 arrowParens: 'always', // 箭头函数参数始终使用括号 };

完整的代码规范体系

openEuler官网的代码规范不仅仅停留在工具层面，还建立了完整的规范文档体系：

1. 命名规范 (rules/naming.md)

• 文件命名：Vue组件使用PascalCase，API模块使用api-前缀
• 类型命名：SigItemT（单条数据）、SigListT（列表数据）、SigQueryT（查询参数）
• 路径别名：~@/指向新版源码，@/指向旧版源码（仅兼容）

2. 组件规范 (rules/components.md)

• 组件结构：严格按照<script>→<template>→<style>顺序
• OpenDesign优先：必须使用OpenDesign组件库，禁止原生HTML替代
• SSR安全：浏览器API只能在onMounted或import.meta.client中访问

3. TypeScript规范 (rules/typescript.md)

• 严格模式：TypeScript配置启用strict: true，不得降低
• 类型定义：使用interface定义对象结构，type定义联合类型
• 禁止any：尽量避免使用any类型，特殊情况需要注释说明

4. 样式规范 (rules/styling.md)

• CSS变量：统一使用OpenDesign的设计令牌
• 响应式设计：使用预定义的断点mixin
• 深度选择器：覆盖组件样式时使用:deep()选择器

开发工作流中的代码规范

提交前检查

虽然项目的husky预提交钩子当前处于注释状态，但开发者应该在提交前手动运行：

pnpm lint # 检查JavaScript/TypeScript代码 pnpm lint:style # 检查样式代码 pnpm build # 确保构建成功

CI/CD流程检查清单

在持续集成流程中，openEuler官网要求：

• pnpm lint无error（warn级别需要评估）
• pnpm lint:style无error
• pnpm build构建无报错
• 中英文双语页面均已验证
• 无console.log或debugger残留
• commit信息符合type(scope): 描述格式

常见问题与解决方案

问题1：ESLint报告未使用的变量

解决方案：使用下划线前缀忽略该变量

// ✅ 正确做法 try { await fetchData(); } catch (_error) { // 忽略错误 } // ❌ 错误做法 try { await fetchData(); } catch (error) { // 空的catch块会被ESLint警告 }

问题2：样式嵌套过深

解决方案：遵循BEM规范，嵌套不超过3层

// ✅ 正确做法 .sig-card { &__header { &__title { // 最多3层嵌套 } } } // ❌ 错误做法 .sig-card { .header { .title { .icon { .text { // 嵌套过深，难以维护 } } } } }

问题3：硬编码颜色值

解决方案：使用CSS变量

// ✅ 正确做法 .card { background: var(--o-color-white); color: var(--o-color-info1); } // ❌ 错误做法 .card { background: #ffffff; color: #000000; }

最佳实践建议

1. 开发前准备

在开始开发前，先运行pnpm install安装依赖，这会自动同步OpenDesign技能到.claude/skills/目录。

2. 代码编写

遵循项目规范，优先使用OpenDesign组件，避免重复造轮子。所有Vue API必须显式导入，因为VitePress没有自动注入功能。

3. 代码提交

提交前务必运行lint检查，确保代码质量。对于涉及国际化的修改，必须同步更新中英文双语文件。

4. 代码评审

在代码评审中，重点关注：

• 是否使用了正确的路径别名（~@/而非@/）
• 是否遵循了TypeScript严格模式
• 样式是否使用了CSS变量和响应式mixin
• 是否正确处理了SSR安全性

总结

openEuler社区官网通过ESLint、StyleLint和Prettier的完美结合，建立了一套完整的代码质量控制体系。这套体系不仅提高了代码质量，还大大提升了团队协作效率。无论您是经验丰富的开发者还是刚接触开源的新手，遵循这些规范都能让您更快地融入openEuler社区，为这个优秀的开源项目贡献代码。

记住，好的代码规范就像交通规则——它可能看起来有些限制，但最终会让所有人的旅程更加安全和高效。现在就开始使用这些工具，提升您的代码质量吧！

【免费下载链接】openEuler-portalThe repository of openEuler portal项目地址: https://gitcode.com/openeuler/openEuler-portal