11ai-npm-publishing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Npm Publishing

Npm 发布

Overview

概述

Use this skill to make a repo publish-ready and to publish it safely with a short, repeatable workflow.

Prefer the smallest set of changes that gets the package publishable. Keep package contents explicit, verify the tarball before publish, and treat auth and org permissions as separate from package configuration.

使用这个skill可以让代码库具备发布条件，并通过简短可复用的工作流安全地完成发布。

优先使用最少的修改让包满足发布要求。保持包内容明确，发布前校验tarball，将鉴权和组织权限与包配置分开处理。

Workflow

工作流

Inspect the package root. Read
```
package.json
```
, check the intended entry point, and inspect the folders that should ship. If
```
semantic-release
```
is configured, check for a dedicated release config file such as
```
.releaserc.js
```
and treat that as the source of truth over older inline config examples.
Align package metadata with the intended publish target. Ensure the scoped package name is correct. Set
```
"private": false
```
when the package must publish. Add
```
"publishConfig": { "access": "public" }
```
for public scoped packages. Set
```
main
```
or
```
exports
```
to a real entry file. Add a
```
files
```
array when the package should publish only selected paths.
Protect secrets and local publish config. Ignore
```
.env
```
files in
```
.gitignore
```
. Prefer reading
```
NPM_TOKEN
```
from a local
```
.env
```
file instead of hardcoding credentials in
```
package.json
```
.
Add or update repo-local publish commands. If the repo needs a reusable publish flow, add a small Node script rather than a long inline one-liner in
```
package.json
```
. Keep the script at a stable path such as
```
./scripts/publish-public-w-local-token.cjs
```
. Prefer a temporary npm config file over passing the token on the command line. Use the helper at scripts/publish-with-local-token.cjs as the starting point when the repo does not already have its own version.
Verify publish contents before release. Run
```
npm pack --dry-run
```
or the repo's equivalent script. Confirm the tarball includes the intended files and excludes local secrets or unrelated workspace files.
Choose the publish mode. For one-off local publishing, use a repo-local helper that reads
```
NPM_TOKEN
```
from
```
.env
```
. For automated publishing from GitHub, prefer
```
semantic-release
```
on pushes to
```
main
```
. When the repo already uses
```
semantic-release
```
, preserve the existing config shape, plugin order, and workflow naming unless the user explicitly wants a migration.
Publish. For scoped public packages, use
```
npm publish --access public
```
. If the repo uses a local token helper, ensure
```
.env
```
contains
```
NPM_TOKEN=...
```
first. If the repo uses
```
semantic-release
```
, ensure the workflow has
```
GITHUB_TOKEN
```
and an
```
NPM_TOKEN
```
secret available.
Troubleshoot failures by category. For package-content issues, revisit
```
main
```
,
```
exports
```
, and
```
files
```
. For 403 errors, separate "wrong credentials" from "org requires 2FA or bypass-enabled token." For local permission or shell issues, inspect the execution environment before changing npm config. For automated releases that do not trigger, inspect branch filters, workflow permissions, and commit message format. For
```
semantic-release
```
trying to publish
```
1.0.0
```
for an already-published package, bootstrap the repo with the existing published version tag before rerunning release automation.

检查包根目录。读取
```
package.json
```
，检查预期的入口点，查看需要发布的文件夹。如果已经配置了
```
semantic-release
```
，检查是否有专门的发布配置文件（如
```
.releaserc.js
```
），并将其作为优先于旧的内联配置示例的事实标准。
让包元数据与预期的发布目标对齐。确保作用域包名称正确。当包需要发布时，设置
```
"private": false
```
。为公开的作用域包添加
```
"publishConfig": { "access": "public" }
```
。将
```
main
```
或
```
exports
```
设置为真实存在的入口文件。当包仅需要发布指定路径时，添加
```
files
```
数组。
保护密钥和本地发布配置。在
```
.gitignore
```
中忽略
```
.env
```
文件。优先从本地
```
.env
```
文件读取
```
NPM_TOKEN
```
，而不是在
```
package.json
```
中硬编码凭证。
添加或更新代码库本地的发布命令。如果代码库需要可复用的发布流程，添加一个简短的Node脚本，而不是在
```
package.json
```
中写很长的内联单行命令。将脚本放在稳定的路径下，例如
```
./scripts/publish-public-w-local-token.cjs
```
。优先使用临时npm配置文件，而不是在命令行中传递令牌。当代码库没有自带的发布脚本时，可以使用scripts/publish-with-local-token.cjs中的工具作为起点。
发布前校验发布内容。运行
```
npm pack --dry-run
```
或者代码库中对应的等价脚本。确认tarball包含预期的文件，排除了本地密钥或者无关的工作区文件。
选择发布模式。对于一次性本地发布，使用从
```
.env
```
读取
```
NPM_TOKEN
```
的代码库本地辅助工具。对于从GitHub自动发布的场景，优先使用推送到
```
main
```
分支时触发的
```
semantic-release
```
。当代码库已经在使用
```
semantic-release
```
时，保留现有的配置结构、插件顺序和工作流命名，除非用户明确需要迁移。
发布。对于公开作用域包，使用
```
npm publish --access public
```
。如果代码库使用本地令牌辅助工具，首先确保
```
.env
```
中包含
```
NPM_TOKEN=...
```
。如果代码库使用
```
semantic-release
```
，确保工作流可以获取到
```
GITHUB_TOKEN
```
和
```
NPM_TOKEN
```
密钥。
按类别排查故障。对于包内容问题，重新检查
```
main
```
、
```
exports
```
和
```
files
```
配置。对于403错误，区分“凭证错误”和“组织要求2FA或者启用了旁路的令牌”两种情况。对于本地权限或者shell问题，在修改npm配置前先检查执行环境。对于没有触发的自动发布，检查分支过滤器、工作流权限和提交信息格式。对于
```
semantic-release
```
试图为已经发布过的包发布
```
1.0.0
```
的问题，在重新运行发布自动化前，给代码库打上已发布的现有版本标签。

Quick Checks

快速检查项

Entry file exists at the path named by
```
main
```
or
```
exports
```
```
files
```
includes the paths that should ship
```
publishConfig.access
```
is
```
"public"
```
for public scoped packages
```
.env
```
is ignored by git
```
npm pack --dry-run
```
output looks correct
Active npm account or token has permission to publish under the target scope

```
main
```
或
```
exports
```
指定路径下的入口文件存在
```
files
```
包含了需要发布的路径
公开作用域包的
```
publishConfig.access
```
设置为
```
"public"
```
```
.env
```
被git忽略
```
npm pack --dry-run
```
的输出符合预期
活跃的npm账号或者令牌有权限在目标作用域下发布

References

参考资料

Read references/publish-checklist.md for a concise pre-publish checklist and common failure modes. Read references/semantic-release.md when the repo should publish automatically from GitHub Actions.

阅读references/publish-checklist.md获取简洁的发布前检查清单和常见故障模式。当代码库需要通过GitHub Actions自动发布时，阅读references/semantic-release.md。

Scripts

脚本

Use scripts/publish-with-local-token.cjs as a reusable template when a repo needs to publish with

NPM_TOKEN

stored in a root

.env

on Windows, macOS, or Linux.

当代码库需要使用存储在根目录

.env

中的

NPM_TOKEN

在Windows、macOS或Linux上发布时，可以使用scripts/publish-with-local-token.cjs作为可复用模板。