将命令行界面与 clasp 搭配使用

如需在终端（而非 Apps 脚本编辑器）中开发和管理 Google Apps 脚本项目，请使用开源工具 clasp。

clasp Codelab 简要介绍了所有 clasp 功能。

功能

clasp包含以下功能：

在本地开发

借助 clasp，您可以在本地开发 Apps 脚本项目。在自己的计算机上编写代码，完成后将其上传到 Apps 脚本。您还可以下载现有的 Apps 脚本项目，以便离线编辑。在构建 Apps 脚本项目时，可以使用您喜爱的开发工具，例如 git。

管理部署版本

创建、更新和查看项目的多个部署。

结构化代码

借助 clasp，您可以将代码整理到目录中，当您将代码上传到 script.google.com 时，这些目录会保留。例如：

# On script.google.com:
├── tests/slides.gs
└── tests/sheets.gs

# Locally:
├── tests/
│   ├─ slides.gs
│   └─ sheets.gs

项目类型

您可以使用 clasp 来管理独立脚本项目和容器绑定脚本项目。

独立项目

独立项目在 Google 云端硬盘中显示为单独的文件。您可以使用 clasp create 命令创建新的独立脚本。

容器绑定项目

容器绑定项目会附加到 Google 文档、Google 表格、Google 幻灯片或 Google 表单文件。您可以使用 clasp create 命令创建附加到新文件的新容器绑定脚本。您还可以使用 --parentId 标志将新脚本附加到现有文件。

其他项目类型

clasp 还支持为 Web 应用和 API 创建脚本。

要求

clasp 使用 Node.js 编写，并通过 npm 工具分发。在使用 clasp 之前，您必须安装 Node.js 20.0.0 版或更高版本。安装 Node.js 需要管理员权限。

安装

安装 Node.js 后，请使用以下 npm 命令安装 clasp：

npm install @google/clasp -g

安装完成后，您可以在计算机上的任何目录中使用 clasp 命令。

使用 clasp

使用 clasp 从命令行处理各种任务。本部分介绍了使用 clasp 进行开发时要使用的常见操作。

登录

此命令会登录并授权管理您的 Google 账号的 Apps 脚本项目。运行后，系统会要求您登录存储 Apps 脚本项目的 Google 账号。

clasp login

退出

此命令会退出命令行工具。请使用 clasp login 重新登录，以便重新向 Google 进行身份验证，然后再继续使用 clasp。

clasp logout

新建 Apps 脚本项目

此命令会在当前目录中创建一个新脚本，并提供可选的脚本标题。

clasp create [scriptTitle] [--type <projectType>] [--parentId <parentId>]

此命令使用以下可选参数：

• scriptTitle：脚本项目的标题。
• --type <projectType>：要创建的项目类型。允许的值包括 standalone、docs、sheets、slides、forms、webapp 和 api。
• --parentId <parentId>：现有 Google 云端硬盘文件（文档、表格、幻灯片或表单）的 ID，新脚本项目应绑定到该文件。

此命令还会在当前目录中创建两个文件：

• 存储脚本 ID 的 .clasp.json 文件。
• 包含项目元数据的 appsscript.json 项目清单文件。

克隆现有项目

此命令会在当前目录中克隆现有项目。脚本必须由您的 Google 账号创建或与您的 Google 账号共享。您可以通过提供脚本 ID 来指定要克隆的脚本项目。您可以克隆独立项目和容器绑定项目。

如需查找项目的脚本 ID，请执行以下操作：

1. 打开 Apps 脚本项目。
2. 点击左侧的项目设置图标 settings。

3. 在 ID 下，复制脚本 ID。

   clasp clone

下载脚本项目

此命令会将 Apps 脚本项目从 Google 云端硬盘下载到您计算机的文件系统中。

clasp pull

上传脚本项目

此命令会将脚本项目的所有文件从您的计算机上传到 Google 云端硬盘。

clasp push

列出项目版本

此命令会列出脚本项目的每个版本的编号和说明。

clasp versions

部署已发布的项目

将脚本项目部署为 Web 应用、Google Workspace 加购项或可执行文件。在脚本编辑器中、项目清单中或使用 clasp 创建部署。

如需部署使用 clasp 的项目，请先创建 Apps 脚本项目的不可变版本。版本是脚本项目的“快照”，类似于只读的分支版本。

clasp version [description]

此命令会显示新创建的版本号。使用该编号部署和取消部署项目的实例：

clasp deploy [version] [description]
clasp undeploy <deploymentId>

此命令会使用新版本和说明更新现有部署：

clasp redeploy <deploymentId> <version> <description>

列出部署

此命令会列出脚本项目的部署 ID、版本及其说明。

clasp deployments

在 Apps 脚本编辑器中打开项目

此命令会在 Apps 脚本编辑器中打开脚本项目。 编辑器会在默认网络浏览器中以新标签页的形式启动。

clasp open-script

为 clasp 开源项目做出贡献

在 GitHub 上为 clasp 贡献代码。

使用 clasp 和 GitHub Actions 为 Apps 脚本实现 CI/CD

本指南介绍了如何使用 clasp 和 GitHub Actions 为 Google Apps 脚本项目设置自动化代码检查、测试和部署。

1. 前提条件

在开始之前，请完成要求中的设置步骤。

您还需要：

• GitHub 代码库。
• 已在 script.google.com/home/usersettings 启用的 Apps 脚本 API。

2. 在 CI 中进行身份验证

由于 CI runner 无法打开浏览器进行 OAuth，因此您需要将凭据存储为 GitHub Secrets：

.clasprc.json 中的刷新令牌可授予对您的 Apps 脚本项目的访问权限。 将其视为敏感凭据并定期进行轮替。

将 .clasprc.json 和 .clasp.json 添加到 .gitignore。这些文件包含凭据，绝不应提交。

3. CI 工作流 - 对 PR 进行 Lint 和测试

.github/workflows/ci.yml：

name: CI
on:
  pull_request:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6.3
      - uses: actions/setup-node@v6.3
        with:
          node-version: "20"
          cache: npm
      - run: npm ci
      - run: npm run lint

4. CD 工作流 - 在合并时部署

.github/workflows/deploy.yml：

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: npm
      - run: npm ci
      - run: npm run lint && npm test
      - name: Setup clasp credentials
        run: |

          echo '${{ secrets.CLASPRC_JSON }}' > ~/.clasprc.json
          echo '${{ secrets.CLASP_JSON }}' > .clasp.json

      - name: Push and version
        run: |
          npx @google/clasp push --force
          npx @google/clasp version "$(git rev-parse --short HEAD)"

--force 标志可在不经确认的情况下覆盖远程代码。此流水线就位后，请避免在 Apps 脚本编辑器中进行手动修改，因为代码库将成为单一可信来源。

5. 多环境部署

对于单独的开发/预演/生产环境，请为每个环境创建一个不同的 Apps 脚本项目，并将其配置存储为单独的 Secret（CLASP_JSON_DEV、CLASP_JSON_STAGING、CLASP_JSON_PROD）。在工作流中，根据要部署的分支将相应的 Secret 写入 .clasp.json。

问题排查

延伸阅读

• GitHub Actions 文档