# @devenvy/code-guidelines 中文文档

规范地址：https://npmcn.com/package/%40devenvy/code-guidelines/

版本：4\.0\.0
npm 元数据更新时间：2026-11-10T22:44:09.766Z
中文译文更新时间：2026-11-12T02:56:13.058Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40devenvy/code-guidelines
原文对照：https://npmcn.com/package/%40devenvy/code-guidelines/?lang=original
项目主页：https://github.com/devenvy/code-guidelines-ecma#readme
源码仓库：https://github.com/devenvy/code-guidelines-ecma

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：150 kB，71 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.13\.0 \|\| \>=24
- 运行依赖：6 个
- peer 依赖：knip ^6\.41\.0，eslint ^10\.12\.0，prettier ^3\.9\.0，typescript ~6\.0\.2，angular-eslint ^22\.6\.0，typescript-eslint ^8\.71\.1，@vitest/eslint-plugin ^1\.6\.27
- 首次发布：2026-10-12T18:42:48.398Z
- 最新版本发布：2026-11-10T22:44:09.449Z
- 近 30 天下载量：4831（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

用于JavaScript,TypeScript和Angular的DevEnvy代码指南:ESLint,Prettier,tsconfig基和Repo基线CLI.

## 安装

```sh
npm install @devenvy/code-guidelines
```

也可以使用：`pnpm add @devenvy/code-guidelines`、`yarn add @devenvy/code-guidelines`、`bun add @devenvy/code-guidelines`

## README

# @devenvy/代码指南

DevEnvy JavaScript、TypeScript和TypeScript共享的提示、格式、TypeScript、编辑器和 git基线 角地库. ECMAScript兄弟会 [代码指南-多特网](https://github.com/devenvy/code-guidelines-dotnet)。 。 。 .

-   **ESLint 语录** 一个 `createConfig()` 调用: 核心、 字迹- slint( 类型意识) 、 导入命令 、, angular-eslint(TypeScript +模板)和Vitest,每个规则都明确决定.
-   **高级** ——为一切进行格式化;ESLint从不与之作对.
-   **tsconfig 基础** ——严格节点,浏览器,角和平面JavaScript的编译器设置.
-   **国 际** —— 说 `init` 设一回所, `check` 在漂移或被削弱的配置上失败了, `sync` 更新 管理的文件 .

## 快开始

```sh
# Plain JavaScript (browser)
pnpm add -D --allow-build '!unrs-resolver' @devenvy/code-guidelines eslint prettier knip
pnpm exec code-guidelines init --env browser --no-typescript

# Node / TypeScript
pnpm add -D --allow-build '!unrs-resolver' @devenvy/code-guidelines eslint prettier knip typescript typescript-eslint @types/node
pnpm exec code-guidelines init --env node

# Angular
pnpm add -D --allow-build '!unrs-resolver' @devenvy/code-guidelines eslint prettier knip typescript typescript-eslint angular-eslint
pnpm exec code-guidelines init --angular --prefix app
```

npm的操作方式相同(`npm i -D …`, (中文(简体) ), `npx code-guidelines …`) (中文(简体) ).

`--allow-build '!unrs-resolver'` 记录 pnpm 不运行安装脚本的决定 `unrs-resolver` (导入插件的解析器;它的预建二进制安装没有它). pnpm 失败 在未决定构建脚本时安装, 所以 `init` 另设 `allowBuilds: unrs-resolver: false` 内 `pnpm-workspace.yaml` (工作空间根的, 对于工作空间包) 除非它已经 `true` 或者说 `false`,以及 `check` 需要一个决定。 使用 pnpm 的项目 `permissions` 设置它在那里决定 `init` 财务报告和审定财务报表 `check` 离开文件.

一个项目只为它所使用的特性安装工具. 除了ESLint之外的一切 普雷蒂埃 且 knip 是一个可选的对等点, 只有在它的特性在 :

| 特性 | 安装 |
| --- | --- |
| 每个项目 | `eslint`, (中文(简体) ), `prettier`, (中文(简体) ), `knip` |
| 类型脚本( 默认) | `typescript`, (中文(简体) ), `typescript-eslint` |
| 角 (正数)`--angular`(中文(简体) ) | `angular-eslint` |
| 维特( V)`--vitest`(中文(简体) ) | `@vitest/eslint-plugin` |

`init` 打印缺失的安装命令,并打开特性 没有软件包, 命令运行失败 。 一个简单的 JavaScript 工程从不需要 类型脚本,只有一个例外: `@vitest/eslint-plugin` 在打字机的公用设施上, 因此,允许维特带 `typescript` ,作为该插件的依赖性(没有配置).

`init` 写道:

| 文件 | 什麽 |
| --- | --- |
| `eslint.config.mjs` | `createConfig({...})` 选择( 缺席时创建) |
| `tsconfig.json` | 类型脚本工程: 扩展 `@devenvy/code-guidelines/tsconfig/<base>.json`; 现有选项正在迁移, 已经设置的选项已被删除 |
| `package.json` | `"prettier"` 键,脚本(`lint`, (中文(简体) ), `format`, (中文(简体) ), `format:check`, (中文(简体) ), `typecheck` 用于类型脚本, `knip`, (中文(简体) ), `guidelines:check`, (中文(简体) ), `test:ci` 与 `--vitest`)和a 数据 `codeGuidelines` 你的选择记录 |
| `.nvmrc` | `24` (缺席时创建) |
| `.editorconfig`, (中文(简体) ), `.gitattributes`, (中文(简体) ), `.gitignore`, (中文(简体) ), `.prettierignore` | 管理区块; 保留您自己在区块外的内容 |
| `.vscode/extensions.json`, (中文(简体) ), `.vscode/settings.json` | 推荐的扩展名和格式/固定保存密钥合并; 保留您的其他设置 |
| `pnpm-workspace.yaml` | pnpm 项目 : `allowBuilds` 决定 `unrs-resolver` 如果缺少; 保留您的其他设置 |

现有 `eslint.config.*`, (中文(简体) ), `.eslintrc*`, (中文(简体) ), `.prettierrc*` 或者说 `prettier.config.*` 文件停止 `init` 在它写东西之前 重运行 `--force` 来代替他们.

## ESLint 语录

```js
// eslint.config.mjs
import { createConfig } from '@devenvy/code-guidelines/eslint';

export default createConfig(
  {
    rootDir: import.meta.dirname,
    env: 'browser',
    vitest: true,
    angular: { prefix: 'app' },
  },
  // any extra flat configs are appended last
  { files: ['scripts/**'], rules: { 'no-warning-comments': 'error' } },
);
```

### 选项

| 选项 | 默认 |  |
| --- | --- | --- |
| `rootDir` | 所需经费 | 根 tsconfig 的目录,通常 `import.meta.dirname` |
| `env` | 所需经费 | `'browser'` 或者说 `'node'` globals 用于源文件 。 根工具配置( R)`*.config.*`) 总是获得节点环球 |
| `typescript` | `true` | 机型识别字体-斜体 `.ts/.mts/.cts`。 。 。 . `false` 用于平版 JavaScript (不需要类型Script 包) |
| `untypedFiles` | `[]` | 每个 tsconfig 外的 TS 文件( 如. `['scripts/**']`),无类型信息被闪烁. 根号 `*.config.ts` 文件总是未类型 |
| `vitest` | `false` | `true` 或者说 `{ files }`默认文件 : `**/*.{spec,test}.{ts,mts,cts,js,mjs,cjs}` |
| `angular` | `false` | `{ prefix, controlComponents? }`。 。 。 . `prefix` 是组件/方向选择器的字符串或数组. `controlComponents` 为标签协会列出自制形式控制的组件 |
| `importOrder.internal` | `[]` | 额外的Regex来源作为内部进口处理,例如:. `['^@app/']`。 。 。 . `^@devenvy/`, (中文(简体) ), `^@/` 财务报告和审定财务报表 `^~/` 已建为 |
| `ignores` | `[]` | 额外的全球忽略. `dist`, (中文(简体) ), `coverage`, (中文(简体) ), `.angular`, (中文(简体) ), `out-tsc`, (中文(简体) ), `node_modules` 财务报告和审定财务报表 `*.min.js` 总是被忽略 |

每个街区都被命名了 `devenvy/<layer>/<part>`; 使用 `npx eslint --inspect-config` 完全看出来 适用于文件的内容.

### 增加和放松规则

附加的配置可能开启共享配置所遗留的规则,或者提高严重程度. `code-guidelines check` 失败于任何比共享配置更弱的东西( 请参见 [国 际](https://npmcn.com/package/%40devenvy/code-guidelines/#readme-cli)因此,一个 规则只有在审查中可见的情况下才放宽:

-   单行: `// eslint-disable-next-line <rule> -- <reason>` (未使用的禁用是错误);
-   生成或销售的文件: `ignores` 选项;
-   在所有 tsconfig 外输入脚本文件: `untypedFiles` 选项.

### 执行什么

规则表 [`src/eslint/rules`](https://npmcn.com/package/%40devenvy/code-guidelines/src/eslint/rules) 是有效的配置 : 每条规则 每一个插件船 都按其严重性列出 令人惊讶 `off`s 带一个理由。 A 类 规则一个更新的插件版本添加到您的项目中, 直到此软件包的发布决定为止 这个 要点 :

-   保证安全`no-floating-promises`, (中文(简体) ), `no-misused-promises`, (中文(简体) ), `await-thenable`页:1 `no-unsafe-*` 家庭 家庭 家庭, `no-explicit-any`, (中文(简体) ), `no-unnecessary-condition`, (中文(简体) ), `no-deprecated`。 。 。 .
-   `no-magic-numbers` (忽略 - 1, 0, 1, 数组索引, 默认值, 缩略语和只读类) 属性);在测试和根工具配置中放松.
-   角: OnPush,信号(`prefer-signals`, (中文(简体) ), `prefer-output-emitter-ref`, (中文(简体) ), `inject()` 在顶上, 控制流,模板访问. 无文件名后缀假设: Angular 20+ 无后缀文件 (单位:千美元)`user-profile.ts`) 与 `*.component.ts`。 。 。 .
-   进口订单 内建 外建 外建 内建 外建 外建 外建 外建 外建 外建 外建 外 外 外 外 外 外 外 外 外 外 外 外 外 外 外 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 相 (单位:千美元)`import-x/no-cycle`,使用 TypeScript 解析器).

只有这些层才会关闭规则 : `no-undef` 用于TS文件,无类型文件,测试文件放松, 财务报告和审定财务报表 `eslint-config-prettier` (与 `curly` (原始内容存档于2019-10-21). re-unitation.

## 高级

```json
{ "prettier": "@devenvy/code-guidelines/prettier" }
```

角项目使用情况 `@devenvy/code-guidelines/prettier/angular`,用于格式 `*.html` 与 angular 剖析器( 纯度仅推断为 `*.component.html`) (中文(简体) ).

选项 : `printWidth: 100`, (中文(简体) ), `singleQuote: true`, (中文(简体) ), `trailingComma: "all"`, (中文(简体) ), `endOfLine: "lf"`· ; 其他一切都是Pretier的默认.

## 类型脚本

```jsonc
// tsconfig.json
{ "extends": "@devenvy/code-guidelines/tsconfig/node.json", "include": ["src"] }
```

| 基础 | 添加数 |
| --- | --- |
| `base.json` | `strict`, (中文(简体) ), `noImplicitOverride`, (中文(简体) ), `noImplicitReturns`, (中文(简体) ), `noFallthroughCasesInSwitch`, (中文(简体) ), `noPropertyAccessFromIndexSignature`, (中文(简体) ), `noUncheckedIndexedAccess`, (中文(简体) ), `isolatedModules`, (中文(简体) ), `skipLibCheck`, (中文(简体) ), `forceConsistentCasingInFileNames`, (中文(简体) ), `target: ES2022` |
| `node.json` | `module`编号 :`moduleResolution: nodenext`, ES2023, (英语), `types: ["node"]` |
| `browser.json` | `module: preserve`, (中文(简体) ), `moduleResolution: bundler`,DOM 自由号 |
| `angular.json` | 浏览器 + `experimentalDecorators`, (中文(简体) ), `importHelpers`,以及 `angularCompilerOptions` `strictTemplates`, (中文(简体) ), `strictInjectionParameters`, (中文(简体) ), `strictInputAccessModifiers` |
| `js.json` | `allowJs`, (中文(简体) ), `checkJs`, (中文(简体) ), `noEmit` 用于使用 JSDoc 类型检查平版JavaScript 。 未设置 `init`: 通过安装选择加入 `typescript` 并延长时间 |

类型脚本 `~6.0`: typescript-eslint和角编译器尚不支持TypeScript 7.

## 国 际

```sh
code-guidelines check            # read-only; exit 1 with a diff on any drift
code-guidelines sync --dry-run   # show what sync would change
code-guidelines sync             # rewrite managed blocks and keys from the installed version
```

除了管理好的区块和钥匙, `check` 比较实际执行的内容和此软件包:

-   **ESLint 语录**: 每张 `.js`编号 :`.mjs`编号 :`.cjs`编号 :`.ts`编号 :`.mts`编号 :`.cts`编号 :`.html` 文档,项目解决 配置( n)`eslint.config.*`,随着ESLint装入它)相对 `createConfig` 与项目本身 选项。 共享配置插件的文件不能被忽略, 它打开的每个规则必须保留 及其分解器、处理器和网际 选项不得被替换。 选项必须匹配 `codeGuidelines` 选择.
-   **类型脚本**: 每一个 `tsconfig*.json` 必须扩展一个被包装的基数(直接或通过其他 tsconfigs, 相对或从一个软件包), 并且没有人可以关闭基础打开的检查 (单位:千美元)`strict` 和它暗示的每个旗帜, `noUncheckedIndexedAccess`和角质 `strictTemplates` 家庭事务.
-   **高级**数字 : `package.json#prettier` 在此软件包中点数,不存在其他 Pretier 配置.

不包括的: `eslint-disable` 批注(每个批注在使用时可见,未使用) 以及CI是否真的运行这些脚本.

稍后更改选择,请编辑 `codeGuidelines` 内 `package.json` (它选择管理内容,例如 作为 Angular VS 代码扩展)并 `eslint.config.mjs` (它选择了 lint 行为),然后运行 `code-guidelines sync`。 。 。 .

### 除了代码指南-多特网

在全速的重播中 两个软件包管理 `.editorconfig`。这个包只拥有它的标记块, 首先放在后面各节(例如: `[*.cs]`)优先,写作 `root = true` 仅在 没有 `root` 线条存在.

## CI和释放

每个repo拥有自己的工作流程(没有共享/可再使用的工作流程). Devenvy CI公约 [风暴观察](https://github.com/devenvy/storm-watch) 作为参考设置,本文介绍 未选中: 工作流程每回波不同, 静态检查无法区分工作 这没什么用.

-   **`ci.yml`** (充电请求和每周运行一次),每个工作一个:
    -   `lint`数字 : `guidelines:check`, (中文(简体) ), `lint`, (中文(简体) ), `format:check`, (中文(简体) ), `typecheck` (TypeScript项目), `knip` (未使用的文件、导出和依赖), [动作lint](https://github.com/rhysd/actionlint) 财务报告和审定财务报表 [齐兹莫尔语name](https://docs.zizmor.sh/) (GitHub Actions security) (吉特Hub动作安全).
    -   `test`数字 : `test:ci` 包含覆盖阈值和公关摘要.
    -   `build`,加repo特定工作(例如容器烟雾测试,或包件检查).
    -   `audit`:生产依赖性审计,关于拉动请求的信息.
    -   `dependency-review`: 未能在程序外添加脆弱依赖或许可证的公关 允许列表.
    -   `dependabot-auto-merge`,以及 `result`,它需要所有其他工作 并且是唯一一个 需要检查状态.
-   **`scorecard.yml`**数字 : [OpenSSF 计分卡](https://scorecard.dev/) 推进到 `main` 周报. 它自己的工作流程,因为出版结果限制了工作流程可能包含的其他内容.
-   **`codeql.yml`**: 代码和工作流程上的代码QL(`actions`, (中文(简体) ), `javascript-typescript`与 `security-and-quality` 查询,根据拉动请求, `main` 周报 一个工作流程而不是 GitHub 的工作流程 默认设置,所以查询和语言都在寄存器中 `main` 规则要求 结果。 (转出默认设置: GitHub 拒绝一个工作流程的运行结果 。)
-   **`SECURITY.md`**: 支持的版本和与私人脆弱性报告的联系(可在 仓库设置).
-   **`.github/dependabot.yml`** 用7天冷却.
-   Bot 动作( Dependabot auto- immerge) 作为 Devenvy- bot GitHub App 运行—— org 变量 `DEVENVY_BOT_CLIENT_ID`, org 密语 `DEVENVY_BOT_PRIVATE_KEY`两者都作为Deptabot秘密—— 因此合并触发工作流程 `main`,哪个 `GITHUB_TOKEN` 合并不会。 每个符号 只请求其步骤需要的许可.

Repo出版如何是自己的选择. 正在使用的两种样式, 都运行 CI 并证明他们发表的内容(建立出处,SPDX SBOM通过 `pnpm sbom`:

-   **最近来自 `main`** (应用程序,例如:风暴观察):每次推向 `main` 部署现场并推进 容器图像为 `latest` 财务报告和审定财务报表 `sha-<commit>`合并到快速相继队列中,所以 最新的 `main` 在进行中后部署。 版本发布是可选的.
-   **手工切割的释放** (npm软件包,例如这个软件包): 发布一个 GitHub 发布 - `gh release create v1.2.0 --target main --generate-notes`,或发布页——出版 版本(npm 软件包及其版本从标签中设定,图像为 `X.Y.Z` 财务报告和审定财务报表 `X.Y`, (中文(简体) ), (b) 释放资产.

覆盖需要维特的 `json-summary` 财务报告和审定财务报表 `json` 记者; 在测试配置中设定阈值 测试本身在覆盖下降时失败.

## 变动

每个版本中的变化都在 [发布注释](https://github.com/devenvy/code-guidelines-ecma/releases)。 。 。 .

## 许可证

麻省理工学院

## 常见问题

### @devenvy/code-guidelines 是什么？

用于JavaScript,TypeScript和Angular的DevEnvy代码指南:ESLint,Prettier,tsconfig基和Repo基线CLI\.

### 如何安装 @devenvy/code-guidelines？

在项目目录运行 npm install @devenvy/code-guidelines，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：knip（^6\.41\.0）、eslint（^10\.12\.0）、prettier（^3\.9\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 code-guidelines，可以用 npx code-guidelines 直接运行。

### @devenvy/code-guidelines 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @devenvy/code-guidelines 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @devenvy/code-guidelines 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.13\.0 \|\| \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @devenvy/code-guidelines 可以商用吗？

@devenvy/code-guidelines 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @devenvy/code-guidelines 的下载量有多少？

根据 npm 官方下载统计，@devenvy/code-guidelines 在 2026/10/12 – 2026/11/10 这 30 天内被下载 4,831 次，日均约 161 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @devenvy/code-guidelines 还在维护吗？

最新版本 4\.0\.0 发布于 2026/11/11（1 天前）；至今共发布 5 个版本，其中过去 12 个月发布了 5 个；首次发布于 2026/10/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。