Yacl

A lightweight Node.js private proxy registry | Verdaccioverdaccio.org

yalc 是一款为包开发者设计的本地包管理工具，提供比 npm/yarn link 更优的工作流，可在本地环境中共享未发布的开发中包，避免依赖解析和符号链接互操作性问题。

核心优势

• 模拟 npm 发布行为，仅同步应发布的文件，一致性更强。

• 支持文件复制和符号链接两种依赖方式，灵活适配不同场景。

• 生成 yalc.lock 确保依赖版本一致性，支持工作区和单体仓库。

• 可自动同步包更新到所有使用项目，提升开发效率。

安装方式

# npm
npm i yalc -g
# yarn
yarn global add yalc
# pnpm
pnpm add -g yalc

基础命令使用

1. 发布本地包（Publish）

将本地开发的包上传到 yalc 全局存储目录（默认 ~/.yalc）。

# 基础发布（执行生命周期脚本，添加版本哈希签名）
yalc publish

# 发布时不运行生命周期脚本
yalc publish --no-scripts

# 禁用版本哈希签名
yalc publish --no-sig

# 发布后自动同步更新到所有使用该包的项目
yalc publish --push

# 快捷推送命令（常用，默认不运行脚本）
yalc push

# 仅在包内容变更时推送更新
yalc push --changed

# 强制替换包内容
yalc push --replace

# 发布单体仓库中的子项目
yalc publish some-project（子项目目录相对路径）

2. 添加本地包到项目（Add）

在依赖项目中引入 yalc 存储的本地包。

# 基础添加（复制文件到项目 .yalc 目录，修改 package.json）
yalc add my-package（包名）

# 添加指定版本
yalc add my-package@version（版本号）

# 添加为 link 类型依赖（而非 file 类型）
yalc add my-package --link

# 添加到开发依赖（devDependencies）
yalc add my-package --dev

# 不修改 package.json 和 node_modules（适配工作区）
yalc add my-package --pure

# 以 workspace: 协议添加依赖
yalc add my-package --workspace（或 -W）

3. 链接本地包（Link）

类似 npm/yarn link，但从项目 .yalc 目录创建符号链接，不修改 package.json。

yalc link my-package（包名）

4. 更新本地包（Update）

同步本地包的最新版本到项目中。

# 更新指定包到最新版本
yalc update my-package

# 更新所有 yalc 管理的包
yalc update

# 触发包管理器的更新命令（如 npm update）
yalc update --update（或 --upgrade/--up）

5. 移除本地包（Remove）

从项目中删除 yalc 管理的包。

# 移除指定包
yalc remove my-package

# 移除所有 yalc 管理的包
yalc remove --all

6. 管理安装记录（Installations）

查询或清理包的安装记录。

# 查看包已安装到的所有项目
yalc installations show my-package

# 取消发布 yalc 发布的包
yalc installations clean my-package

# 清理已删除项目的安装记录（消除警告）
yalc installations clean

高级功能

1. 暂退与恢复（Retreat & Restore）

临时还原或重新启用 yalc 管理的包。

# 暂退指定包（或 --all 暂退所有）
yalc retreat [my-package]

# 恢复暂退的包
yalc restore

2. 忽略文件配置

• 创建 .yalcignore 文件，添加无需发布的文件（如 README.md），语法同 .gitignore。

• 若需在包中包含 .yalc 文件夹，需在 .npmignore 中添加 !.yalc。

3. Git 集成策略

排除在 Git 之外（临时使用）

• 将 .yalc 和 yalc.lock 添加到 .gitignore。

• 使用 yalc link 避免修改 package.json。

• 预提交钩子中添加 yalc check，防止遗漏移除 yalc 依赖。

纳入 Git 管理（团队共享开发中包）

• 直接提交 .yalc 和 yalc.lock 到仓库，确保团队依赖一致。

• 在 .gitignore 中添加 **/.yalc/**/*.md 排除非代码文件。

4. 工作区适配（Yarn/Pnpm Workspaces）

• 启用工作区的项目中添加包时，默认使用 --pure 模式，不修改 package.json。

• 在项目 package.json 的 workspaces 中添加 .yalc/* 和 .yalc/@*/*，自动同步更新。

• 使用 --no-pure 覆盖默认行为。

5. 自定义配置

• 通过 --store-folder 覆盖全局存储目录：yalc publish --store-folder /custom/path。

• 创建 .yalcrc 文件设置默认选项（如 workspace-resolve=false 禁用 workspace 协议解析，sig=false 禁用版本签名）。

6. 输出控制

• --quiet：仅显示错误信息，禁用其他输出。

• --no-colors：禁用彩色输出。

注意事项

• Windows 用户需确保发布的源代码使用 LF 换行符，否则部分脚本可能失效。

• yalc 完全模拟 npm pack 的文件包含规则，嵌套 .yalc 文件夹需在 package.json 的 files 中明确声明。

• 生命周期脚本执行顺序：发布前（prepublish → prepare → prepublishOnly → prepack → preyalcpublish），发布后（``postyalcpublish → postpack → publish → postpublish`）。