如何创建GitHub Workflow将Stencil.js组件发布至npm并解决问题

第一步：确保package.json配置正确 #

先检查你的package.json，必须通过files字段指定需要发布的目录，否则即使构建完成，npm也不会自动上传这些文件：

{
  "files": [
    "dist/",
    "loader/",
    "package.json",
    "README.md",
    "LICENSE"
  ],
  "scripts": {
    "build": "stencil build" // 确保该构建脚本存在，Stencil默认自带此配置
  }
}

第二步：创建GitHub Workflow文件 #

在仓库的.github/workflows目录下新建publish-to-npm.yml，内容如下：

name: Publish to npm

on:
  push:
    tags:
      - 'v*' # 仅当推送v开头的版本标签（如v1.0.0）时触发发布

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20' # 选择Stencil支持的Node版本，18/20均可
          registry-url: 'https://registry.npmjs.org/'

      - name: Install dependencies
        run: npm ci # 严格按照package-lock.json安装依赖，避免版本不一致

      - name: Build Stencil components
        run: npm run build # 执行构建生成dist和loader目录

      - name: Publish to npm
        run: npm publish --access public # 公开包必须加--access public，私有包可省略
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} # 从GitHub Secrets读取npm认证token

关键配置说明 #

1. 触发逻辑：用tags: ['v*']限定触发条件，只有推送版本标签时才会执行发布，避免日常提交误触发。
2. Node环境与npm认证：setup-node会自动处理npm源和认证，无需修改你仓库中为空的.npmrc文件。
3. 依赖与构建：npm ci适合CI环境，能保证依赖版本一致；npm run build是生成dist/loader目录的核心步骤，必须保留。
4. npm token配置：
   • 去npm官网生成自动化发布token，权限选择Publish。
   • 在GitHub仓库的Settings > Secrets and variables > Actions中新建名为NPM_TOKEN的Secret，填入生成的token。

解决你遇到的问题 #

• 缺失dist/loader目录：Workflow中加入了构建步骤，同时package.json的files字段明确指定了要上传的目录，彻底解决文件缺失问题。
• YAML语法错误：确保Workflow文件用2个空格缩进，所有步骤的name/uses/run等键对齐，禁止用tab缩进。
• npm ERR! 404：
  • 确认你的npm token拥有对应包的发布权限，且包名在npm上未被占用。
  • 如果是带scope的包（如@your-username/feedback-component），必须加--access public参数，同时确保你的npm账号拥有该scope的权限。

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