Add simplified Chinese documentation (#1290)

* build: update vitepress to 1.0.0-beta.6 version * docs: add simplified Chinese translation
2026-09-24 16:59:45 +00:00 · 2024-01-22 17:50:09 +01:00
parent cf79597e42
commit fbbc85e221
8 changed files with 1343 additions and 303 deletions
@@ -22,4 +22,24 @@ export default defineConfig({
      { text: 'Migrating from v4', link: '/migrating-from-v4' },
    ],
  },
+  locales: {
+    root: {
+      label: 'English',
+      lang: 'en',
+    },
+    zh: {
+      label: '简体中文',
+      lang: 'zh-CN',
+      link: '/zh/',
+      themeConfig: {
+        sidebar: [
+          { text: '介绍', link: '/zh/' },
+          { text: '开始使用', link: '/zh/getting-started' },
+          { text: '指南', link: '/zh/guide' },
+          { text: '疑难解答', link: '/zh/troubleshooting' },
+          { text: '从 v4 迁移', link: '/zh/migrating-from-v4' },
+        ],
+      },
+    }
+  }
 })
@@ -0,0 +1,165 @@
+# 开始使用
+
+## 自动 <Badge type="tip" text="推荐" />
+
+`husky-init` 是一个一次性命令，用于快速初始化一个带有 husky 的项目。
+
+::: code-group
+
+```shell [npm]
+npx husky-init && npm install
+```
+
+```shell [pnpm]
+pnpm dlx husky-init && pnpm install
+```
+
+```shell [yarn]
+yarn dlx husky-init --yarn2 && yarn
+```
+
+:::
+
+它将会:
+
+1. 添加 `prepare` 脚本到 `package.json`
+2. 创建一个你能够编辑的 `pre-commit` hook 示例（默认情况下，`npm test` 将在你提交时运行）
+3. 配置 Git hooks 路径
+
+要添加另一个 hook，请使用 `husky add`。例如：
+
+```shell
+npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'
+```
+
+::: info 注意
+对于 Windows 用户，如果在运行 `npx husky add ...` 时看到帮助信息，请尝试使用 `node node_modules/husky/lib/bin add ...`。这不是 husky 代码的问题。
+:::
+
+## 手动
+
+### 安装
+
+1. 安装 `husky`
+
+```shell
+npm install husky --save-dev
+```
+
+2. 启用 Git hooks
+
+```shell
+npx husky install
+```
+
+3. 要在安装后自动启用 Git hooks，请编辑 `package.json`
+
+```shell
+npm pkg set scripts.prepare="husky install"
+```
+
+你应该这样做:
+
+::: code-group
+
+```json [package.json]
+{
+  "scripts": {
+    "prepare": "husky install" // [!code hl]
+  }
+}
+```
+
+:::
+
+::: info 注意
+Yarn 2+ 不支持编写生命周期脚本，所以 husky 需要以不同的方式安装（但这不适用于 Yarn1）。参见 [Yarn 2+ 安装](#yarn-2)。
+:::
+
+## 创建一个 hook
+
+要向 hook 添加命令或创建新的 hook，可以使用 `husky add <file> [cmd]`（再此之前不要忘记执行 `husky install`）。
+
+```shell
+npx husky add .husky/pre-commit "npm test"
+git add .husky/pre-commit
+```
+
+尝试提交
+
+```shell
+git commit -m "Keep calm and commit"
+```
+
+如果 `npm test` 命令执行失败，你的提交会被自动终止。
+
+::: warning 警告
+**想要使用 Yarn 运行命令？Git Bash 在 Windows 上有个问题，请参阅 [在 Windows 上使用 Yarn](./troubleshooting.md#在-windows-上使用-yarn)。**
+:::
+
+_对于 Windows 用户，如果在运行 `npx husky add ...` 时看到帮助信息，请尝试使用 `node node_modules/husky/lib/bin add ...`。这不是 husky 代码的问题，在 npm 8 的最新版本已经修复了。_
+
+### 卸载
+
+```shell
+npm uninstall husky && git config --unset core.hooksPath
+```
+
+## Yarn 2
+
+### 安装
+
+1. 安装 `husky`
+
+```shell
+yarn add husky --dev
+yarn add pinst --dev # ONLY if your package is not private
+```
+
+2. 启用 Git hooks
+
+```shell
+yarn husky install
+```
+
+3. 要在安装后自动启用 Git hooks，请编辑 `package.json`
+
+::: code-group
+
+```js [package.json]
+{
+  "private": true, // ← 你的 package 是私有的，你只需要 postinstall
+  "scripts": {
+    "postinstall": "husky install"
+  }
+}
+```
+
+:::
+
+::: tip 提示
+如果您的软件包不是私有的，并且您正在像 [npmjs.com](https://npmjs.com) 这样的仓库上发布它，那么您需要使用 [pinst](https://github.com/typicode/pinst)\*\* 禁用 postinstall 脚本。否则，当有人安装你的软件包并导致错误时，将运行 postinstall。
+:::
+
+::: code-group
+
+```js [package.json]
+{
+  "private": false, // ← 你的 package 是共有的
+  "scripts": {
+    "postinstall": "husky install",
+    "prepack": "pinst --disable",
+    "postpack": "pinst --enable"
+  }
+}
+```
+
+:::
+
+### 卸载
+
+从 `package.json` 中移除 `"postinstall": "husky install"`，并执行：
+
+```shell
+yarn remove husky && git config --unset core.hooksPath
+```
@@ -0,0 +1,175 @@
+# 指南
+
+## Monorepo
+
+建议在根目录下的 `package.json` 中添加 husky。你可以使用诸如 [lerna](https://github.com/lerna/lerna) 和 filter 之类的工具来仅在已更改的包中运行脚本。
+
+## 自定义目录
+
+如果你想在另一个目录安装 husky，比如 `.config` 目录，你可以在 `install` 命令后面添加参数。示例如下：
+
+::: code-group
+
+```js [package.json]
+{
+  "scripts": {
+    "prepare": "husky install .config/husky"
+  }
+}
+```
+
+:::
+
+另一种情况，如果你的 `package.json` 文件和 `.git` 目录不在同一级目录。例如，`project/.git` 和 `project/front/package.json`。
+
+设计上，`husky install` 必须运行在于 `.git` 相同的目录，但是你可以通过在 `prepare` 脚本中传入一个子目录来改变目录：
+
+::: code-group
+
+```js [package.json]
+{
+  "scripts": {
+    "prepare": "cd .. && husky install front/.husky"
+  }
+}
+```
+
+:::
+
+在你的 hooks 中，你也需要去更改目录：
+
+::: code-group
+
+```shell [.husky/pre-commit]
+# ...
+cd front
+npm test
+```
+
+:::
+
+## 绕过 hooks
+
+你能使用 Git命令的 `-n/--no-verify` 选项来绕过 `pre-commit` 和 `commit-msg` hooks：
+
+```shell
+git commit -m "yolo!" --no-verify
+```
+
+对于没有使用 `--no-verify` 选项的 Git 命令，你可以使用 `HUSKY` 环境变量：
+
+```shell
+HUSKY=0 git push # yolo!
+```
+
+## 在 CI/Docker/Prod 中禁用 husky
+
+在 CI/Docker/Prod上下文中禁用 husky 没有对错之分，这在很大程度上 **取决于你的使用情况**。
+
+### 使用 npm
+
+如果你想阻止 husky 完全安装
+
+```shell
+npm ci --omit=dev --ignore-scripts
+```
+
+或者，你也能明确地禁用 `prepare` 脚本
+
+```shell
+npm pkg delete scripts.prepare
+npm ci --omit=dev
+```
+
+### 使用自定义脚本
+
+您可以创建一个自定义 JS 脚本，有条件地要求使用 husky 和安装 hooks。
+
+::: code-group
+
+```json [package.json]
+"prepare": "node ./prepare.js"
+```
+
+```js [prepare.js]
+const isCi = process.env.CI !== undefined
+if (!isCi) {
+  require('husky').install()
+}
+```
+
+:::
+
+或者在未安装 husky 的情况下，让 `prepare` 脚本无声地失败：
+Or make `prepare` script fail silently if husky is not installed:
+
+```json [package.json]
+"prepare": "node -e \"try { require('husky').install() } catch (e) {if (e.code !== 'MODULE_NOT_FOUND') throw e}\""
+```
+
+### 使用环境变量
+
+你可以在你的 CI 配置文件中，将 `HUSKY` 环境变量设置为 `0`，来禁用 hooks 安装。
+
+另外，大多数持续集成服务器都会设置一个 `CI` 环境变量。你可以在钩子中使用它来检测是否在 CI 中运行。
+
+::: code-group
+
+```shell [.husky/pre-commit]
+# ...
+[ -n "$CI" ] && exit 0
+```
+
+:::
+
+### 使用 is-ci
+
+您还可以在 `prepare` 脚本中使用 [is-ci](https://github.com/watson/is-ci)，有条件地安装 husky
+
+```shell
+npm install is-ci --save-dev
+```
+
+::: code-group
+
+```js [package.json]
+{
+  "scripts": {
+    "prepare": "is-ci || husky install"
+  }
+}
+```
+
+:::
+
+## 测试 hooks
+
+如果要测试 hook，可以在脚本末尾添加 `exit 1` 来终止 git 命令。
+
+::: code-group
+
+```shell [.husky/pre-commit]
+# ...
+exit 1 # Commit will be aborted
+```
+
+:::
+
+## Git-flow
+
+如果使用 [git-flow](https://github.com/petervanderdoes/gitflow-avh/)，需要确保 git-flow hooks 目录设置为使用 husky（默认为 `.husky`）。
+
+```shell
+git config gitflow.path.hooks .husky
+```
+
+**注意:**
+
+- 如果在安装 husky 之后配置 git-flow，那么 git-flow 设置过程将正确地建议使用 `.husky` 目录。
+- 如果您已经为 husky 设置了一个 [自定义目录](#自定义目录)，那么您需要指定这个目录(比如 `git config gitflow. path.hooks. config/husky`)
+
+要将 Git-flow hook 目录 **恢复** 到默认目录，需要重置配置，使其指向默认的 Git hook 目录。
+
+```shell
+git config gitflow.path.hooks .git/hooks
+```
@@ -0,0 +1,81 @@
+[![Financial Contributors on Open Collective](https://opencollective.com/husky/all/badge.svg?label=financial+contributors)](https://opencollective.com/husky)
+
+[![](https://img.shields.io/npm/dm/husky.svg?style=flat)](https://www.npmjs.org/package/husky)
+
+[![Node.js CI](https://github.com/typicode/husky/workflows/Node.js%20CI/badge.svg)](https://github.com/typicode/husky/actions)
+
+> 使现代的原生 Git Hooks 变得简单
+
+Husky 能使你的提交变得更好  🐶 _汪!_
+
+在提交或推送时，你可以用它来 **检查提交信息**、**运行测试**、**检查代码** 等。Husky 支持 [所有 Git hooks](https://git-scm.com/docs/githooks)。
+
+点击 [这里](./getting-started) 开始使用。
+
+## 特点
+
+- 轻量级，零依赖 (`6 kB`)
+- 由现代化的新 Git 特性驱动 (`core.hooksPath`)
+- 遵循 [npm](https://docs.npmjs.com/cli/v8/using-npm/scripts#best-practices) 和 [Yarn](https://yarnpkg.com/advanced/lifecycle-scripts#a-note-about-postinstall) 的 `自动安装` 最佳实践
+- 对用户友好的信息
+- Opt-in/opt-out
+- **支持**
+  - macOS, Linux 和 Windows
+  - Git GUIs
+  - 自定义 hooks 目录
+  - 嵌套项目
+  - Monorepos
+
+## 谁在使用
+
+Husky 被运用在这些伟大的项目中：
+
+- [webpack/webpack](https://github.com/webpack/webpack)
+- [angular/angular](https://github.com/angular/angular)
+- [angular/angular-cli](https://github.com/angular/angular-cli)
+- [angular/components](https://github.com/angular/components)
+- [vercel/hyper](https://github.com/vercel/hyper)
+- [blitz-js/blitz](https://github.com/blitz-js/blitz)
+- [facebook/docusaurus](https://github.com/facebook/docusaurus)
+- [typescript-eslint/typescript-eslint](https://github.com/typescript-eslint/typescript-eslint)
+- [11ty/eleventy](https://github.com/11ty/eleventy)
+- [stylelint/stylelint](https://github.com/stylelint/stylelint)
+- [rollup/rollup](https://github.com/rollup/rollup)
+- [tauri-apps/tauri](https://github.com/tauri-apps/tauri)
+- [NativeScript/NativeScript](https://github.com/NativeScript/NativeScript)
+- [formatjs/formatjs](https://github.com/formatjs/formatjs)
+- [react-bootstrap/react-bootstrap](https://github.com/react-bootstrap/react-bootstrap)
+- [react-dnd/react-dnd](https://github.com/react-dnd/react-dnd)
+- [react-grid-layout/react-grid-layout](https://github.com/react-grid-layout/react-grid-layout)
+- [snabbdom/snabbdom](https://github.com/snabbdom/snabbdom)
+- [logaretm/vee-validate](https://github.com/logaretm/vee-validate)
+- [zenorocha/clipboard.js](https://github.com/zenorocha/clipboard.js)
+- [NodeBB/NodeBB](https://github.com/NodeBB/NodeBB)
+- [ant-design/ant-design](https://github.com/ant-design/ant-design)
+- 还有 [**超过 110 万个项目**](https://github.com/typicode/husky/network/dependents?package_id=UGFja2FnZS0xODQzNTgwNg%3D%3D)
+
+## 相关文章
+
+- [Why husky has dropped conventional JS config](https://blog.typicode.com/husky-git-hooks-javascript-config/)
+- [Why husky doesn't autoinstall anymore](https://blog.typicode.com/husky-git-hooks-autoinstall/)
+
+## 赞助者
+
+你的公司在使用 Husky 吗？询问你的经理或者营销团队是否有兴趣支持这个项目。
+
+<a href="https://opencollective.com/husky/tiers/company/0/website"><img src="https://opencollective.com/husky/tiers/company/0/avatar.svg?avatarHeight=120"></a>
+<a href="https://opencollective.com/husky/tiers/company/1/website"><img src="https://opencollective.com/husky/tiers/company/1/avatar.svg?avatarHeight=120"></a>
+<a href="https://opencollective.com/husky/tiers/company/2/website"><img src="https://opencollective.com/husky/tiers/company/2/avatar.svg?avatarHeight=120"></a>
+<a href="https://opencollective.com/husky/tiers/company/3/website"><img src="https://opencollective.com/husky/tiers/company/3/avatar.svg?avatarHeight=120"></a>
+<a href="https://opencollective.com/husky/tiers/company/4/website"><img src="https://opencollective.com/husky/tiers/company/4/avatar.svg?avatarHeight=120"></a>
+<a href="https://opencollective.com/husky/tiers/company/5/website"><img src="https://opencollective.com/husky/tiers/company/5/avatar.svg?avatarHeight=120"></a>
+<a href="https://opencollective.com/husky/tiers/company/6/website"><img src="https://opencollective.com/husky/tiers/company/6/avatar.svg?avatarHeight=120"></a>
+<a href="https://opencollective.com/husky/tiers/company/7/website"><img src="https://opencollective.com/husky/tiers/company/7/avatar.svg?avatarHeight=120"></a>
+<a href="https://opencollective.com/husky/tiers/company/8/website"><img src="https://opencollective.com/husky/tiers/company/8/avatar.svg?avatarHeight=120"></a>
+<a href="https://opencollective.com/husky/tiers/company/9/website"><img src="https://opencollective.com/husky/tiers/company/9/avatar.svg?avatarHeight=120"></a>
+
+觉得哈士奇有用吗？成为一个支持者，并通过每月在 [Open Collective](https://opencollective.com/husky) 上的捐款来表达你的感激之情。你也可以通过一次性捐赠来给小费。
+
+<a href="https://opencollective.com/husky" target="_blank"><img src="https://opencollective.com/husky/tiers/individual.svg?avatarHeight=32"/></a>
+
+GitHub 的赞助商可以在我的 [个人资料](https://github.com/typicode) 中查看。所有过去和现在的 Open Collective 赞助商都可以在 [这里](https://opencollective.com/husky) 查看。
@@ -0,0 +1,76 @@
+# 从 v4 迁移
+
+## CLI
+
+请参见 [husky-4-to-8](https://github.com/typicode/husky-4-to-8) CLI 以快速从 v4迁移到 v8。
+
+## 手动迁移
+
+如果使用 `npm` 或 `yarn` 调用 `package.json` 脚本，只需将配置文件中的命令 **复制** 到相应的钩子即可：
+
+::: code-group
+
+```js [.huskyrc.json (v4)]
+{
+  "hooks": {
+    "pre-commit": "npm test && npm run foo"
+  }
+}
+```
+
+```shell [.husky/commit-msg (v8)]
+# ...
+npm test
+npm run foo
+```
+
+:::
+
+如果您正在调用本地安装的二进制文件，**现在您需要通过您的包管理器运行它们**：
+
+::: code-group
+
+```js [.huskyrc.json (v4)]
+{
+  "hooks": {
+    "pre-commit": "jest"
+  }
+}
+```
+
+```shell [.husky/commit-msg (v8)]
+# ...
+npx --no jest
+# or
+yarn jest
+```
+
+:::
+
+`HUSKY_GIT_PARAMS` 环境变量现在替换为原生参数 `$1`、`$2`。
+
+::: code-group
+
+```js [.huskyrc.json (v4)]
+{
+  "hooks": {
+    "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
+  }
+}
+```
+
+```shell [.husky/commit-msg (v8)]
+# ...
+npx --no -- commitlint --edit $1
+# or
+yarn commitlint --edit $1
+```
+
+:::
+
+其他环境变量改动：
+
+- `HUSKY_SKIP_HOOKS` 替换为 `HUSKY`。
+- `HUSKY_SKIP_INSTALL` 替换为 `HUSKY`。
+- `HUSKY_GIT_PARAMS` 已被移除。取而代之的是，Git 参数应该直接在脚本中使用（例如 `$1`）。
+- 本地安装工具的 `PATH` 不再自动设置。你需要使用包管理器来运行它们。
@@ -0,0 +1,78 @@
+# 疑难解答
+
+## 找不到命令
+
+如果您在应用程序中运行 Git，而命令可以在终端中找到，这意味着应用程序中的 `PATH` 与终端中的不同。
+
+你可以在终端中使用 `echo $PATH` 命令，然后配置你的应用为相同的值。
+
+如果你使用 `brew` 安装了你的命令，请参阅 [Homebrew FAQ](https://docs.brew.sh/FAQ)，让你的应用程序可以使用你的命令。
+
+最后，如果你正在使用管理版本的脚本，例如 `nvm`、`n`、`rbenv`、`pyenv`......你可以在运行 hooks 之前使用 `~/.huskyrc` 加载必要的脚本。
+Finally, if you're using a script for managing versions like `nvm`, `n`, `rbenv`, `pyenv`, ... you can use `~/.huskyrc` to load the necessary before running hooks.
+
+例如，对于 nvm，可以使用:
+
+::: code-group
+
+```shell [~/.huskyrc]
+# This loads nvm.sh, sets the correct PATH before running hook, and ensures the project version of Node
+export NVM_DIR="$HOME/.nvm"
+
+[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
+
+# If you have an .nvmrc file, we use the relevant node version
+if [[ -f ".nvmrc" ]]; then
+  nvm use
+fi
+```
+
+:::
+
+::: info 注意
+对于某些应用程序（如 VS Code），只需重启应用程序即可解决此问题。在采取上述任何步骤之前，请先尝试一下！\*\*
+:::
+
+## Hooks 未运行
+
+1. 确保文件名中没有错别字。例如 `precommit` 或 `pre-commit.sh` 都是无效名称。有关有效名称，请参阅 Git hooks [文档](https://git-scm.com/docs/githooks)。
+2. 检查 `git config core.hooksPath` 是否返回 `.husky`（或你的自定义 hook 目录）。
+3. 确认钩子文件是可执行的。使用 `husky add` 命令时会自动设置为可执行，但可以运行 `chmod +x .husky/<hookname>` 来修复。
+4. 检查 Git 版本是否大于 `2.9`。
+
+## 卸载后 .git/hooks/ 无法运行
+
+如果卸载 `husky` 后，`.git/hooks/` 中的 hooks 不起作用。运行 `git config --unset core.hooksPath`。
+
+注意：如果 `npm <7` 在卸载 husky 时会自动执行此操作，但现在已不支持 `preuninstall`。
+
+## 在 Windows 上使用 Yarn
+
+在 Windows 上使用 Yarn 和 Git Bash（`stdin 不是 tty`）时，Git hooks 可能会失败。如果用户使用的是 Windows 系统，强烈建议添加以下解决方案。
+
+1. 创建 `.husky/common.sh`:
+
+```shell
+command_exists () {
+  command -v "$1" >/dev/null 2>&1
+}
+
+# Workaround for Windows 10, Git Bash and Yarn
+if command_exists winpty && test -t 1; then
+  exec < /dev/tty
+fi
+```
+
+2. 在使用 Yarn 运行命令的地方输入源代码：
+
+```shell
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+. "$(dirname -- "$0")/common.sh"
+
+yarn ...
+```
+
+## 它能在 Windows 上运行吗？
+
+可以。在 Windows 上安装 Git 时，会附带运行 shell 脚本所需的软件。
@@ -35,7 +35,7 @@
    "@types/node": "^20.1.4",
    "@typicode/eslint-config": "^1.1.0",
    "typescript": "^5.0.4",
-    "vitepress": "^1.0.0-alpha.75"
+    "vitepress": "^1.0.0-beta.6"
  },
  "engines": {
    "node": ">=16"