Pnpm on Liangweidong's blog

FSS 全栈脚手架：pnpm + turbo + husky + lint-staged 实战

Wed, 15 Apr 2020 00:00:00 +0800

什么是 FSS

FSS（Full-Stack Scaffold）= 一套多端共享代码的全栈项目脚手架，结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


fss/
├── apps/
│ ├── app/ # PC 端
│ ├── desktop/ # 桌面端（Tauri）
│ ├── mini-program/ # 小程序
│ └── web/ # 移动端 Web
├── packages/
│ ├── ui/ # 公共 UI 组件
│ └── utils/ # 公共工具
└── global/
 ├── config/
 ├── proto/
 └── scripts/

核心技术栈：

包管理：pnpm（快、节省磁盘）
构建编排：turbo（增量构建、任务编排）
代码规范：ESLint + Prettier + Stylelint
Git 钩子：husky + lint-staged + commitlint
UI 框架：Ant Design + Pro Components

初始化

1. 创建根 package.json

1
2


cd fss
pnpm init

2. 创建 pnpm-workspace.yaml

1
2
3
4
5


# pnpm-workspace.yaml
packages:
 - 'apps/*'
 - 'packages/*'
 - 'global/*'

3. 创建 turbo.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


{
 "$schema": "https://turbo.build/schema.json",
 "globalDependencies": ["**/.env.*local", ".env"],
 "globalEnv": ["NODE_ENV"],
 "pipeline": {
 "build": {
 "dependsOn": ["^build"],
 "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
 },
 "dev": {
 "cache": false,
 "persistent": true
 },
 "lint": {
 "outputs": []
 },
 "test": {
 "dependsOn": ["^build"],
 "outputs": ["coverage/**"]
 },
 "clean": {
 "cache": false
 }
 }
}

4. 安装依赖

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


pnpm add -D -w \
 @eslint/js \
 eslint \
 eslint-plugin-react \
 eslint-plugin-react-hooks \
 eslint-plugin-react-refresh \
 globals \
 typescript-eslint \
 @typescript-eslint/eslint-plugin \
 @typescript-eslint/parser \
 stylelint \
 stylelint-config-standard \
 stylelint-config-recess-order \
 stylelint-scss \
 stylelint-less \
 postcss-less \
 husky \
 lint-staged \
 prettier

# commitlint
pnpm add -D -w @commitlint/cli @commitlint/config-conventional

5. 创建各端

1
2
3
4
5
6
7
8


# 创建一个 PC 端
cd apps
mkdir app && cd app
pnpm create vite admin-pc --template react-ts

# 移除默认 ESLint
pnpm remove -D @eslint/js eslint eslint-plugin-react-hooks \
 eslint-plugin-react-refresh globals typescript-eslint

ESLint + Prettier 统一

`.eslintrc.cjs`（根目录）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


module.exports = {
 root: true,
 env: { browser: true, es2022: true, node: true },
 extends: [
 'eslint:recommended',
 'plugin:@typescript-eslint/recommended',
 'plugin:react/recommended',
 'plugin:react-hooks/recommended',
 'prettier',
 ],
 parser: '@typescript-eslint/parser',
 plugins: ['@typescript-eslint', 'react', 'react-hooks'],
 rules: {
 'react/react-in-jsx-scope': 'off',
 '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
 },
};

`.prettierrc`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{
 "printWidth": 100,
 "tabWidth": 2,
 "useTabs": false,
 "semi": true,
 "singleQuote": true,
 "trailingComma": "all",
 "bracketSpacing": true,
 "arrowParens": "always"
}

`.stylelintrc.cjs`

1
2
3
4
5
6
7


module.exports = {
 extends: ['stylelint-config-standard', 'stylelint-config-recess-order'],
 rules: {
 'no-descending-specificity': null,
 'selector-class-pattern': null,
 },
};

husky + lint-staged

启用 husky

1
2


pnpm run prepare
npx husky add .husky/pre-commit "npx lint-staged"

`.lintstagedrc.json`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


{
 "*.{ts,tsx,js,jsx}": [
 "eslint --fix",
 "prettier --write"
 ],
 "*.{css,scss,less}": [
 "stylelint --fix",
 "prettier --write"
 ],
 "*.{json,md}": [
 "prettier --write"
 ]
}

commitlint

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// commitlint.config.js
module.exports = {
 extends: ['@commitlint/config-conventional'],
 rules: {
 'type-enum': [
 2,
 'always',
 ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'chore', 'revert'],
 ],
 'subject-max-length': [2, 'always', 72],
 },
};

1

npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

提交示例：

1
2


git commit -m "feat: 添加用户管理模块"
git commit -m "fix(auth): 修复 token 过期跳转"

turbo 命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


turbo --version

# 执行所有子项目的 build
pnpm turbo run build

# 执行指定子项目
pnpm turbo run dev --filter=admin-pc

# 所有子项目构建
pnpm turbo run build

# 代码校验
pnpm turbo run lint

# 单元测试
pnpm turbo run test

子项目依赖管理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# 给指定子项目加 antd
pnpm add antd --filter=admin-pc

# 路由
pnpm add react-router --filter=admin-pc

# 状态管理
pnpm add @reduxjs/toolkit react-redux --filter=admin-pc

# CSS
pnpm add -D unocss --filter=admin-pc
pnpm add @unocss/reset --filter=admin-pc
pnpm add @unocss/preset-wind3 --filter=admin-pc

UI 共享包（packages/ui）

1
2
3
4
5
6
7


cd packages
mkdir ui && cd ui
pnpm init

# 装 antd
pnpm add antd
pnpm add -D @types/react @types/react-dom react react-dom

packages/ui/src/index.ts：

1
2


export { default as Button } from './Button';
export { default as Table } from './Table';

在 admin-pc 引用：

1
2


// apps/admin-pc/src/App.tsx
import { Button, Table } from '@fss/ui';

desktop 子项目（Tauri + React）

1
2
3
4
5


cd apps
mkdir desktop && cd desktop

# 初始化 pnpm workspace
pnpm init

1
2
3
4


# pnpm-workspace.yaml
packages:
 - '../app'
 - '.'

1
2
3
4
5


# 加 Tauri CLI
pnpm add -D @tauri-apps/cli@latest -w

# 初始化 Tauri
pnpm tauri init

开发：

1

pnpm tauri dev

打包：

1

pnpm tauri build

全局目录（global/）

1
2
3
4
5
6
7


global/
├── config/ # 通用配置
│ ├── eslint/
│ ├── stylelint/
│ └── prettier/
├── proto/ # Protobuf 定义
└── scripts/ # 构建脚本

性能优化

turbo 远程缓存：turbo.json 加 remoteCache: { teamSlug: "...", token: "..." }
pnpm 设置：~/.npmrc 加 auto-install-peers=true / strict-peer-dependencies=false
构建缓存：outputs: ["dist/**", ".next/**"] 命中增量

下一步

想把 PC 端 + 移动端用一套代码覆盖，看 2021-07-15《PC 前端技术选型》
想用 Tauri 2.x 替代 Electron，看 2020-05-15《Tauri 2.x 跨平台桌面应用》

参考资料

pnpm workspace：https://pnpm.io/workspaces
Turborepo 文档：https://turbo.build/repo/docs
husky：https://typicode.github.io/husky/
lint-staged：https://github.com/lint-staged/lint-staged
Ant Design：https://ant.design/

包管理工具：npm / yarn / pnpm 全对比与 yarn berry 升级

Tue, 15 Aug 2017 00:00:00 +0800

为什么写这篇：2016 年 yarn 1.0 横空出世，靠并行安装和 lockfile 把 npm 5 之前的"装包慢、依赖飘"问题锤了一遍。2018 年 pnpm 出现，靠"硬链接 + 内容寻址存储"把磁盘占用压到极致。2020 年 yarn 2（berry）做 Plug’n’Play，零 node_modules。2025 年的新项目几乎只在这三者之间选。本文用一份"选型决策树"和"命令对照表"收尾。

适用读者：要给新项目选包管理器；被同事的 pnpm install 报错困扰；要从 yarn 1 升级到 berry/pnpm。

前置知识：用过 npm 即可。

1. 三巨头历史与设计哲学

工具	诞生	维护方	核心思路
npm	2010	npm Inc.（被 GitHub 收购）	官方默认，与 Node 同生共死
yarn 1.x	2016-10	Facebook（已移交社区）	并行安装 + lockfile + 离线缓存
pnpm	2017	Zoltan Kochan	硬链接 + 内容寻址，磁盘节约 50%+
yarn berry (v2+)	2020-01	Yarn 团队	PnP（Plug’n’Play）—— 抛弃 node_modules
bun	2022	Oven	Zig 编写的 JS 运行时 + 极快包管理器（兼容 npm script）

核心设计差异：

npm/yarn 1：每个项目的 node_modules 是平铺的"半 hoist"结构（依赖被提升到顶层 node_modules），节省空间但导致"幽灵依赖"——你能 require('xxx') 但它不在 package.json 里

pnpm：用 .pnpm/<pkg>@<version>/node_modules/<pkg> 软链接隔离 + node_modules/<pkg> 软链接到 node_modules/.pnpm——真实依赖树且零幽灵依赖

yarn berry PnP：根本不要 node_modules，每个包用 .pnp.cjs 文件描述"谁在哪"。启动快、装包快，但所有老工具链（webpack、jest、tsc）都得配 PnP 适配器

2. 安装与版本管理

2.1 npm

1
2
3
4
5
6


node -v # Node 自带 npm
npm -v

# 升级
npm install -g npm@latest
npm update -g

2.2 yarn 1.x

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


npm install -g yarn
yarn -v

# 升级
npm install -g yarn@latest
yarn self-update

# 装指定 tag
yarn self-update stable
yarn self-update canary

2.3 pnpm

1
2
3
4
5
6
7
8


# 推荐用独立安装脚本（避免污染全局 npm）
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Windows
iwr https://get.pnpm.io/install.ps1 -useb | iex

# 升级
pnpm self-update

2.4 bun（备选）

1

curl -fsSL https://bun.sh/install | bash

3. 命令对照速查表

任务	npm	yarn 1.x	pnpm
初始化	`npm init`	`yarn init`	`pnpm init`
一键安装	`npm install`	`yarn` / `yarn install`	`pnpm install`
添加依赖	`npm i pkg`	`yarn add pkg`	`pnpm add pkg`
添加开发依赖	`npm i -D pkg`	`yarn add -D pkg`	`pnpm add -D pkg`
全局装	`npm i -g pkg`	`yarn global add pkg`	`pnpm add -g pkg`
卸载	`npm uninstall pkg`	`yarn remove pkg`	`pnpm remove pkg`
升级	`npm update`	`yarn upgrade`	`pnpm update`
跑 script	`npm run dev`	`yarn dev`	`pnpm dev`
清理缓存	`npm cache clean --force`	`yarn cache clean`	`pnpm store prune`
列出已装	`npm list`	`yarn list`	`pnpm list`
装指定版本	`npm i pkg@1.2.3`	`yarn add pkg@1.2.3`	`pnpm add pkg@1.2.3`
只装 prod	`npm i --production`	`yarn install --production`	`pnpm install --prod`
锁文件	`package-lock.json`	`yarn.lock`	`pnpm-lock.yaml`

4. 配置文件

4.1 npm：`.npmrc`

放在项目根目录或 ~/.npmrc（用户级）：

1
2
3
4


registry=https://registry.npmmirror.com
save-exact=true
package-lock=true
audit=false

4.2 yarn 1：`.yarnrc`

1

registry "https://registry.npmmirror.com"

4.3 pnpm：`.npmrc`（与 npm 兼容）+ `pnpm-workspace.yaml`

1
2
3
4


# .npmrc
registry=https://registry.npmmirror.com
auto-install-peers=true # 自动装 peer dep
shamefully-hoist=true # 兼容老 webpack/jest

5. lockfile：依赖的"唯一真理"

Why lockfile 必交 Git：不交 lockfile，同一个 package.json 在不同时间/不同网络下能装出完全不同的依赖树——经典 bug"我这能跑你那不能跑"。

工具	文件名	是否必交 Git	是否必交 lockfile 即可不重装
npm 5+	`package-lock.json`	✅	✅
yarn 1	`yarn.lock`	✅	✅
pnpm	`pnpm-lock.yaml`	✅	✅
yarn berry	`yarn.lock`	✅	配合 `.yarn/cache`

1
2
3
4


# 不读 lockfile 强制重装（出问题时偶尔用）
npm install --no-package-lock
yarn install --no-lockfile
pnpm install --no-lockfile

6. 镜像加速与代理

6.1 永久改源

1
2
3


npm config set registry https://registry.npmmirror.com
yarn config set registry https://registry.npmmirror.com
pnpm config set registry https://registry.npmmirror.com

6.2 nrm 一键切换

1
2
3
4
5
6
7
8
9


npm install -g nrm
nrm ls
# npm ---------- https://registry.npmjs.org/
# yarn --------- https://registry.yarnpkg.com/
# cnpm --------- https://r.cnpmjs.org/
# taobao ------- https://registry.npmmirror.com/
# tencent ------ https://mirrors.cloud.tencent.com/npm/

nrm use taobao

6.3 代理

1
2
3
4
5
6
7


# 命令行（项目级）
npm config set proxy http://127.0.0.1:1081
npm config set https-proxy http://127.0.0.1:1081

# 环境变量（用户级）
export HTTP_PROXY=http://127.0.0.1:1081
export HTTPS_PROXY=http://127.0.0.1:1081

7. 常见排错

7.1 循环依赖错误

1
2


npm error ERESOLVE could not resolve
npm error Conflicting peer dependency: react@17 vs react@18

解决：

1
2
3


npm install xxx --legacy-peer-deps
yarn install --ignore-peer-deps
pnpm install --shamefully-hoist

7.2 GitHub SSH 权限问题

1
2


npm ERR! code 128
npm ERR! git@github.com: Permission denied (publickey)

解决：

1
2
3
4
5
6
7


# 1. 生成密钥
ssh-keygen -t ed25519 -C "<YOUR_EMAIL>"

# 2. 把 ~/.ssh/id_ed25519.pub 内容加到 GitHub → Settings → SSH and GPG keys

# 3. 验证
ssh -T git@github.com

7.3 浏览器数据自动更新错误

1

browserslist: Caniuse was updated

说明 browserslist 数据陈旧。重新跑 npx update-browserslist-db@latest。

7.4 装包后跑起来报错

经典排错四件套：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# 1. 清缓存 + 删 node_modules
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

# 2. 升 Node
nvm use 20

# 3. 检查 peer dep
npm ls react

# 4. 看完整错误
npm install --verbose 2>&1 | head -100

8. yarn berry / pnpm：升级路径与坑

8.1 yarn 1 → yarn berry (v2+)

1
2
3
4
5
6


# 在项目目录
yarn set version berry
# → Saving the new release in .yarn/releases/yarn-3.2.1.cjs

yarn --version
# 3.2.1

升级后会自动生成：

1
2
3
4
5
6
7


.yarn/
├── cache/ # 离线包缓存（建议 commit）
├── unplugged/ # 编译型 native 模块临时目录
└── releases/ # yarn 二进制（建议 commit）

.yarnrc.yml # 新版配置
.pnp.cjs # PnP 依赖图

.gitignore 必须加：

1
2
3
4


/.pnp.*
.yarn/cache
.yarn/unplugged
.yarn/install-state.gz

设置 npm registry：

1
2


yarn config set npmRegistryServer https://registry.npmmirror.com
yarn # 装包

8.2 yarn berry 的核心——PnP

PnP（Plug’n’Play）没有 node_modules！所有包都在 .yarn/cache/，启动时通过 .pnp.cjs 的"依赖图"直接定位文件。

优点：

装包速度比 yarn 1 快 2-3 倍
启动速度提升（无文件系统 IO）
杜绝幽灵依赖（包必须显式声明在 deps）

坑：

很多老工具链不兼容——必须用 PnP 适配版
- Webpack 4/5：装 @yarnpkg/pnpify 然后跑 yarn pnpify webpack
- Jest：装 jest-pnp-resolver
- TypeScript：配 pnpPlugin 解析器
- VSCode：装 ZipFS 扩展才能读 .yarn/cache

小贴士：Berry 默认是 PnP。如果你不想抛弃 node_modules，加 .yarnrc.yml：
1
nodeLinker: node-modules
这样就像 yarn 1 一样工作，但还是 yarn berry 的安装器。

8.3 从 npm/yarn 1 迁到 pnpm

1
2
3
4
5
6
7
8


# 1. 装 pnpm
npm install -g pnpm

# 2. 删除旧 lockfile
rm package-lock.json yarn.lock

# 3. 用 pnpm 装
pnpm install

坑：老项目里大量 require('xxx') 但 xxx 不在 package.json 的"幽灵依赖"，pnpm 装完会报错。两种解法：

找到所有 require/import 实际用到的包，补到 package.json

在 .npmrc 加 shamefully-hoist=true（pnpm 模拟 npm 的"提升"行为）——不推荐，治标不治本

9. monorepo 工作区

包管理工具的"工作区（workspace）“能力，让多个子包共享一个 node_modules，是 monorepo 的基石。

9.1 yarn 1 workspaces

package.json：

1
2
3
4


{
 "private": true,
 "workspaces": ["packages/*", "apps/*"]
}

9.2 pnpm workspaces（最推荐）

pnpm-workspace.yaml：

1
2
3


packages:
 - 'apps/*'
 - 'packages/*'

1
2
3


pnpm -F <pkg> add <dep> # 只给某个子包加依赖
pnpm -r run build # 跑所有子包的 build
pnpm --filter <pkg>... <cmd> # 依赖关系图上跑命令

9.3 npm workspaces（7+ 支持）

package.json：

1
2
3


{
 "workspaces": ["packages/*"]
}

1
2


npm install lodash -w @myorg/utils
npm run build --workspaces

monorepo 工具链对比：

工具适合规模特点

npm/yarn/pnpm workspaces 小团队零额外依赖

Lerna 中型已并入 Nx

Nx 中大型任务编排、缓存、依赖图分析最强

Turborepo 中大型增量构建、远程缓存、零配置

Rush 大型微软维护，企业级权限与发布流水线

10. 选型决策树

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


新项目选包管理器？

├─ 想 0 学习成本、纯前端小项目
│ └─ npm ✓
│
├─ monorepo + 多包共享
│ ├─ 小型（< 5 包）→ npm / yarn 1 workspaces
│ ├─ 中型（5-20 包）→ pnpm workspaces ✓
│ └─ 大型（> 20 包）→ pnpm + Turborepo / Nx
│
├─ 老 npm 项目维护，不想折腾
│ └─ npm 9+ ✓（性能已与 yarn 1 持平）
│
├─ 公司有私服（Nexus / Verdaccio）镜像严格
│ └─ pnpm（lockfile 完整，依赖提升少）
│
├─ 极致装包速度、CI 跑得快
│ └─ pnpm（内容寻址，复用 100%）
│
└─ 抛弃 node_modules、要 PnP 黑科技
 └─ yarn berry (PnP) —— 仅当你团队接受重写所有工具链时

小贴士：CI 环境装包时，pnpm 默认不用网络——因为依赖都已"硬链接"到全局 store。建议在 package.json 旁边放 .npmrc：
1
prefer-frozen-lockfile=true
锁文件没变就直接复用 node_modules，CI 启动时间从 90s 降到 15s。

小结

npm / yarn / pnpm / berry 的设计哲学各有不同。2025 年的"默认推荐"是 pnpm——装包快、磁盘省、workspace 体验最好、monorepo 生态最完整（Turbo/Nx 优先支持）。老项目维护用 npm 就好，不要为了追新而迁移。yarn berry 仅在大公司、复杂 monorepo、追求极致启动速度时考虑。

工具	适合规模	特点
npm/yarn/pnpm workspaces	小团队	零额外依赖
Lerna	中型	已并入 Nx
Nx	中大型	任务编排、缓存、依赖图分析最强
Turborepo	中大型	增量构建、远程缓存、零配置
Rush	大型	微软维护，企业级权限与发布流水线

Pnpm on Liangweidong's blog

FSS 全栈脚手架：pnpm + turbo + husky + lint-staged 实战

什么是 FSS

初始化

1. 创建根 package.json

2. 创建 pnpm-workspace.yaml

3. 创建 turbo.json

4. 安装依赖

5. 创建各端

ESLint + Prettier 统一

.eslintrc.cjs（根目录）

.prettierrc

.stylelintrc.cjs

husky + lint-staged

启用 husky

.lintstagedrc.json

commitlint

turbo 命令

子项目依赖管理

UI 共享包（packages/ui）

desktop 子项目（Tauri + React）

全局目录（global/）

性能优化

下一步

参考资料

包管理工具：npm / yarn / pnpm 全对比与 yarn berry 升级

目录

1. 三巨头历史与设计哲学

2. 安装与版本管理

2.1 npm

2.2 yarn 1.x

2.3 pnpm

2.4 bun（备选）

3. 命令对照速查表

4. 配置文件

4.1 npm：.npmrc

4.2 yarn 1：.yarnrc

4.3 pnpm：.npmrc（与 npm 兼容）+ pnpm-workspace.yaml

5. lockfile：依赖的"唯一真理"

6. 镜像加速与代理

6.1 永久改源

6.2 nrm 一键切换

6.3 代理

7. 常见排错

7.1 循环依赖错误

7.2 GitHub SSH 权限问题

7.3 浏览器数据自动更新错误

7.4 装包后跑起来报错

8. yarn berry / pnpm：升级路径与坑

8.1 yarn 1 → yarn berry (v2+)

8.2 yarn berry 的核心——PnP

8.3 从 npm/yarn 1 迁到 pnpm

9. monorepo 工作区

9.1 yarn 1 workspaces

9.2 pnpm workspaces（最推荐）

9.3 npm workspaces（7+ 支持）

10. 选型决策树

小结

参考资料

`.eslintrc.cjs`（根目录）

`.prettierrc`

`.stylelintrc.cjs`

`.lintstagedrc.json`

4.1 npm：`.npmrc`

4.2 yarn 1：`.yarnrc`

4.3 pnpm：`.npmrc`（与 npm 兼容）+ `pnpm-workspace.yaml`