# front-dome **Repository Path**: zk_daydayup/front-dome ## Basic Information - **Project Name**: front-dome - **Description**: 学习前端 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-12-20 - **Last Updated**: 2026-01-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 项目代码规范与开发环境配置指南 本文档整合了项目核心配置文件、代码规范校验脚本、开发环境重置流程，为团队提供统一的开发规范与环境配置参考，便于协作与问题排查。 学习地址 : https://www.bilibili.com/video/BV1oz421q7BB 当前进度: 20251227-028 ## 一、核心配置文件说明 ### 1. .stylelintrc.json（CSS 规范配置） ```json { "root": true, "extends": "stylelint-config-standard", "rules": { "comment-empty-line-before": null, "property-no-vendor-prefix": null, "property-no-deprecated": null, "color-hex-length": null, "color-function-alias-notation": null, "alpha-value-notation": null, "comment-whitespace-inside": null, "no-empty-source": true, "max-nesting-depth": 4 } } ``` | 配置项 | 取值 | 含义说明 | |--------------------------------------|---------------------------|-----------------------------------------| | root | true | 标记为根配置文件，停止向上查找其他配置 | | extends | stylelint-config-standard | 继承 Stylelint 官方标准规则集 | | comment-empty-line-before | null | 禁用“注释前需空行”规则，灵活调整注释格式 | | property-no-vendor-prefix | null | 禁用“禁止浏览器私有前缀”规则，允许使用 -webkit-、-moz- 等前缀 | | property-no-deprecated | null | 禁用“禁止废弃属性”规则，兼容旧项目/特殊场景 | | color-hex-length | null | 禁用“强制16进制颜色长度”规则，允许简写（#fff）或全称（#ffffff） | | color-function-alias-notation | null | 禁用“颜色函数别名限制”规则，允许 rgb()/rgba() 等写法 | | alpha-value-notation | null | 禁用“透明度值格式限制”规则，允许 0.5 或 50% 格式 | | comment-whitespace-inside | null | 禁用“注释内部强制空格”规则，灵活调整注释格式 | | indentation | 2 | 缩进使用 2 个空格，统一 CSS 格式 | | no-empty-source | true | 禁止空样式文件，避免无效配置 | | declaration-block-trailing-semicolon | always | 属性值末尾必须加分号，规范 CSS 书写 | | max-nesting-depth | 4 | 选择器嵌套深度不超过 4 层，避免样式层级过深难以维护 | ### 2. package.json（项目核心配置） ```json { "name": "front-dome", "version": "1.0.0", "type": "module", "dependencies": { "naive-ui": "^2.43.2" }, "devDependencies": { "npm-run-all": "^4.1.5", "standard": "^17.1.0", "stylelint": "^16.2.1", "stylelint-config-standard": "^36.0.0", "htmlhint": "^1.1.4" }, "eslintConfig": { "env": { "browser": true, "es2021": true, "node": true }, "extends": "standard" }, "scripts": { "lint:html": "htmlhint \"**/**.html\" || exit 0", "lint:js": "standard \"**/*.js\" --env browser || exit 0", "lint:js:fix": "standard --fix \"**/*.js\" --env browser || exit 0", "lint:css": "stylelint \"**/*.css\" || exit 0", "lint:css:fix": "stylelint \"**/*.css\" --fix || exit 0", "lint": "run-p lint:html lint:js lint:css", "lint:fix": "run-s lint:js:fix lint:css:fix" } } ``` | 配置项 | 含义说明 | |--------------------------|-----------------------------------------------------------| | type: module | 启用 ESModule 模块规范，支持 import/export 语法 | | dependencies | 生产环境依赖（如 naive-ui 组件库） | | devDependencies | 开发环境依赖（校验工具：htmlhint/standard/stylelint；脚本管理：npm-run-all） | | eslintConfig.env.browser | 让 Standard.js 识别浏览器全局 API（如 alert、window） | | eslintConfig.env.node | 让 Standard.js 识别 Node.js 全局 API（如 require、module），兼容配置文件 | | scripts | 定义代码校验/修复命令（详情见“代码规范校验脚本说明”） | ### 3. .htmlhintrc（HTML 规范配置） ```json { "root": true, "rules": { "id-unique": true, "attr-duplication": true, "tag-close": true, "attr-quotes": [ "error", "double" ], "doctype-first": true, "title-require": true, "tag-name-lowercase": true, "attr-name-lowercase": true, "empty-tag-not-self-closed": true, "indentation": [ "error", 2 ], "inline-style-disabled": false, "tag-deprecated": true, "attr-value-no-space": true } } ``` | 配置项 | 取值 | 含义说明 | |---------------------------|---------------------|------------------------------------------| | root | true | 标记为根配置文件，停止向上查找其他配置 | | id-unique | true | 禁止重复 ID，避免 DOM 选择器冲突 | | attr-duplication | true | 禁止标签属性重复（如 `
`） | | tag-close | true | 标签必须闭合（如 `
` 必须对应 `
`） | | attr-quotes | ["error", "double"] | 属性值必须用双引号包裹，规范书写格式 | | doctype-first | true | HTML 文档必须以 DOCTYPE 开头，确保浏览器标准模式渲染 | | title-require | true | `` 中必须包含 `` 标签，提升页面 SEO 友好性 | | tag-name-lowercase | true | 标签名必须小写，统一 HTML 书写规范 | | attr-name-lowercase | true | 属性名必须小写，统一 HTML 书写规范 | | empty-tag-not-self-closed | true | 禁止空标签非自闭合（除 `<br>`、`<img>` 等特殊标签） | | indentation | ["error", 2] | 缩进使用 2 个空格，统一代码格式 | | inline-style-disabled | false | 允许内联样式（如需禁止可改为 true） | | tag-deprecated | true | 禁止使用废弃标签（如 `<font>`、`<center>`） | | attr-value-no-space | true | 属性值禁止包含多余空格，避免解析异常 | ## 二、忽略文件配置说明 忽略文件用于指定无需参与代码规范校验的目录或文件，避免对第三方依赖、打包产物等非开发源码进行无效校验，提升校验效率。 ### 1. .htmlhintignore（HTML 校验忽略配置） 作用：指定 htmlhint 工具无需校验的 HTML 相关文件/目录 | 忽略项 | 说明 | |------------------------|----------------------------| | node_modules/ | 忽略依赖目录（无需校验第三方 HTML） | | dist/、build/、dist-ssr/ | 忽略打包产物（无需校验编译后的 HTML） | | vendor/ | 忽略第三方静态资源目录 | | *.temp.html、*.tmp.html | 忽略临时 HTML 文件 | | *.min.html | 忽略压缩后的 HTML 文件（已压缩，无需格式校验） | ### 2. .standardignore（JS 校验忽略配置） 作用：指定 standard（JS 校验工具）无需校验的 JS 相关文件/目录 | 忽略项 | 说明 | |----------------------------------------------|--------------------------| | node_modules/ | 忽略依赖目录（无需校验第三方 JS） | | dist/、build/、dist-ssr/ | 忽略打包产物（无需校验编译后的 JS） | | *.config.js、vite.config.js、webpack.config.js | 忽略配置文件（按需单独校验） | | vendor/ | 忽略第三方静态资源目录 | | *.temp.js、*.tmp.js | 忽略临时 JS 文件 | | *.min.js | 忽略压缩后的 JS 文件（已压缩，无需格式校验） | | __tests__/、*.test.js、*.spec.js | 忽略测试相关文件（若单独配置校验规则） | ### 3. .stylelintignore（CSS 校验忽略配置） 作用：指定 stylelint 工具无需校验的 CSS 相关文件/目录 | 忽略项 | 说明 | |-------------------------|---------------------------| | node_modules/ | 忽略依赖目录（无需校验第三方 CSS） | | dist/、build/、dist-ssr/ | 忽略打包产物（无需校验编译后的 CSS） | | vendor/ | 忽略第三方静态资源目录 | | *.temp.css、*.tmp.css | 忽略临时 CSS 文件 | | *.min.css | 忽略压缩后的 CSS 文件（已压缩，无需格式校验） | | *.vars.css、*.mixins.css | 忽略样式变量/混合器文件（若单独管理） | ## 三、开发环境重置流程 当项目出现依赖冲突、缓存异常、安装失败等问题时，按以下步骤彻底重置环境（Windows PowerShell 环境）： ### 1. 清理旧依赖与缓存 ```powershell # 1. 删除项目本地依赖目录（递归删除，强制清除只读文件） Remove-Item -Path ./node_modules -Recurse -Force # 2. 删除旧的依赖版本锁定文件（可选，如需完全重置依赖版本） Remove-Item -Path ./package-lock.json -Force # 3. 强制清除npm全局缓存，避免缓存导致的安装异常 npm cache clean --force ``` ### 2. 配置 npm 镜像（永久切换淘宝镜像） ```powershell # 1. 永久设置npm镜像为淘宝npmmirror（官方最新地址，原淘宝镜像已废弃） npm config set registry https://registry.npmmirror.com/ # 2. 验证镜像切换是否成功（输出 https://registry.npmmirror.com/ 即为成功） npm config get registry ``` ### 3. 重新安装依赖与验证 ```powershell # 1. 根据package.json安装所有项目依赖（自动生成node_modules与package-lock.json） npm install # 2. 验证依赖安装成功，执行代码规范全量校验 npm run lint ``` ## 四、代码规范校验/修复脚本说明 通过 `npm run 脚本名` 执行对应的校验或修复操作，具体说明如下： | 脚本名称 | 核心执行逻辑 | 核心作用 | |--------------|-------------------------------------------------|----------------------------------------| | lint:html | htmlhint 递归校验所有.html文件（遵循.htmlhintignore规则） | 校验HTML规范（重复ID、未闭合标签等），失败不中断脚本 | | lint:js | standard 递归校验所有.js文件（浏览器环境，遵循.standardignore规则） | 校验JS规范（格式/逻辑错误），识别alert等浏览器API，失败不中断脚本 | | lint:js:fix | standard 自动修复所有.js文件（浏览器环境，遵循.standardignore规则） | 自动修复JS格式错误（引号/空格/分号等），保留逻辑错误，失败不中断脚本 | | lint:css | stylelint 递归校验所有.css文件（遵循.stylelintignore规则） | 校验CSS规范（缺少分号、废弃属性等），失败不中断脚本 | | lint:css:fix | stylelint 自动修复所有.css文件（遵循.stylelintignore规则） | 自动修复CSS格式错误（空格/分号/引号等），保留无效属性，失败不中断脚本 | | lint | 并行执行lint:html+lint:js+lint:css | 一键全量校验HTML/JS/CSS，一次性输出所有错误，效率更高 | | lint:fix | 串行执行lint:js:fix+lint:css:fix | 一键自动修复JS+CSS格式错误，避免并行冲突，不支持HTML修复 | ## 五、补充注意事项 1. **路径要求**：所有命令需在项目根目录执行 2. **权限说明**：删除 `node_modules` 或清除缓存时若提示“权限不足”，请以“管理员身份”打开 PowerShell； 3. **镜像切换**：如需恢复 npm 官方镜像，执行命令 `npm config set registry https://registry.npmjs.org/`； 4. **自动修复局限**：`lint:js:fix` 与 `lint:css:fix` 仅修复格式错误，逻辑错误（如未使用变量、无效属性值）需手动修改； 5. **团队协作**： - 必须上传 `package.json`、`package-lock.json` 及所有配置文件（.stylelintrc.json、.htmlhintrc等）到代码仓库，确保团队规范一致； - 新成员拉取代码后，仅需执行 `npm install` 即可搭建一致的开发与校验环境； 6. **脚本使用建议**：提交代码前执行 `npm run lint` 全量校验，格式混乱时先执行 `npm run lint:fix` 自动修复。 ```plaintext front-dome/ └── static-to-vue-project/ # 你的项目目录 ├── public/ # 公共静态资源（Vue 拓展后无需改动） │ ├── favicon.ico │ └── index.html # 静态入口（Vue 拓展后作为 Vue 入口 HTML） ├── src/ # 核心资源（静态/Vue 共用） │ ├── assets/ # 样式/脚本/图片 │ │ ├── css/ │ │ ├── js/ │ │ └── images/ │ └── pages/ # 页面文件（静态 HTML → 后续改为 Vue 组件） │ ├── home.html │ └── about.html ├── .gitignore └── README.md ```