带Scope的npm包中package.json的man配置无法生效问题排查

问题描述 #

我开发了一个npm包@xkeshav/gh-repo-care，已在package.json中配置了man字段，且生成了.1后缀的man手册文件。包的文件夹结构如下：

.
├── bin
│   └── health-check.js
├── CHANGELOG.md
├── docs
│   └── gh-repo-care.md
├── LICENSE
├── man
│   └── git-repo-care.1
├── package.json
├── package-lock.json
├── README.md
├── repo-care.code-workspace
├── src
│   ├── assets
│   ├── helpers
│   ├── index.js
│   └── other

package.json核心配置片段：

{
  "name": "@xkeshav/gh-repo-care",
  "directories": {
    "bin": "bin",
    "man": "man",
    "doc": "docs"
  },
  "man": "man/gh-repo-care.1",
  "scripts": {
    "man": "marked-man --version \"git-open $npm_package_version\" --manual \"Git manual\" --section 1 docs/gh-repo-care.md > man/git-repo-care.1"
  }
}

执行npm publish --tag alpha发布后，无论是项目内安装还是全局安装，运行man @xkeshav/gh-repo-care或man gh-repo-care都无法调用手册，请问问题出在哪里？

问题根源 #

• 文件名与配置不匹配：package.json的man字段指定的是man/gh-repo-care.1，但实际生成的文件是man/git-repo-care.1，npm无法找到正确的手册文件。
• 生成脚本错误：scripts.man命令中输出的文件名是git-repo-care.1，和包名gh-repo-care不对应，导致发布后手册无法关联到包。
• scoped包的man命名规范：对于带@scope的包，man文件名需与包名对应（可使用gh-repo-care.1或@xkeshav/gh-repo-care.1），否则man命令无法识别。

解决步骤 #

1. 修正man文件生成脚本
   修改package.json中的scripts.man，将输出文件名改为与包名一致的gh-repo-care.1，同时修正版本描述中的工具名：

   "man": "marked-man --version \"gh-repo-care $npm_package_version\" --manual \"Git manual\" --section 1 docs/gh-repo-care.md > man/gh-repo-care.1"
   

2. 重新生成man文件
   运行命令生成正确命名的手册文件：

   npm run man
   

   确认man文件夹下的文件为gh-repo-care.1。

3. 重新发布包
   删除旧的alpha标签（可选）并重新发布：

   npm dist-tag rm @xkeshav/gh-repo-care alpha
   npm publish --tag alpha --access=public
   

4. 测试手册调用

   • 全局安装后直接调用：

     npm install -g @xkeshav/gh-repo-care@alpha
     man gh-repo-care
     

   • 项目内安装时，可直接指定文件路径测试：

     man ./node_modules/@xkeshav/gh-repo-care/man/gh-repo-care.1
     

   • 若仍无法调用，可尝试刷新man数据库（部分Linux环境需要）：

     mandb
     

内容的提问来源于stack exchange，提问作者xkeshav