VS Code Looker 扩展程序使用入门

借助 VS Code 的 Looker 扩展程序，您可以直接在本地桌面环境中开发 LookML。它提供丰富的语法突出显示功能、与 Looker 实例的双向文件同步功能，并与 AI 编码代理集成，实现“氛围编程 (vibe coding)”。

该扩展程序是使用 Visual Studio Code (VS Code) 框架构建的，支持基于 VS Code IDE 的 IDE，例如以下 IDE 和编码工具：

  • Claude Code
  • Codex
  • 光标
  • Kiro
  • VS Code
  • Windsurf
  • Zed

VS Code 的 Looker 扩展程序不支持 IntelliJ 和 Eclipse 等非 VS Code 分叉的 IDE。

本指南介绍了如何设置扩展程序并进行身份验证。

AI 赋能的工作流

适用于 VS Code 的 Looker 扩展程序是支持 AI 的代理式开发工作流的一部分，用于编辑和创建 LookML 文件。如需启用此工作流，请配置以下工具：

  • 适用于 VS Code 的 Looker 扩展程序。
  • 基于 VS Code 的本地 IDE。IDE 必须包含内置 AI 智能体（例如 Cursor），或者，如果 IDE 不包含内置 AI 智能体（例如基本 VS Code），则 IDE 必须与独立智能体工具（例如 Gemini CLI 或 Claude Code）集成。如需了解如何将 IDE 连接到代理，请参阅本地 IDE 的文档。
  • MCP 服务器，例如 MCP Toolbox for Databases。

如需详细了解依托 AI (技术) 的工作流，请参阅 Looker 中的 AI 辅助开发（氛围编程 (vibe coding)）文档页面。

准备工作

在安装扩展程序之前，您必须满足以下要求：

  • 连接到 AI 工具：如果您计划使用 AI 辅助开发，请将 IDE 和 AI 智能体连接到 MCP Toolbox for Databases。例如，如需查看将 MCP Toolbox 连接到 Gemini CLI 的示例配置，请参阅将 Looker 与 MCP、Gemini CLI 和其他智能体搭配使用文档。如需了解更多详情，请参阅工具的文档。
  • Looker 权限：您必须拥有要修改的任何模型的 develop Looker 权限。
  • Looker 实例：您的实例必须运行 Looker 26.6 或更高版本。
  • Git 安装：您必须在本地机器上安装 Git，才能克隆和管理 LookML 代码库。
  • 项目配置：LookML 项目必须配置为使用 Git。
  • OAuth 客户端 ID：如果您使用 OAuth 身份验证（推荐），则必须从 Looker 管理员处获取 OAuth 客户端 ID。

Admin 设置

如果您的组织使用 OAuth 进行身份验证，Looker 管理员必须在 Looker 管理界面中将 Looker 扩展程序注册为 VS Code 的 OAuth 客户端。

使用 Looker API Explorer 设置 OAuth 集成。您可以使用以下任一方法访问 API Explorer：

  • 如果您的 Looker 实例已安装 API 探索器，您可以使用以下网址格式访问它：

    https://LOOKER_INSTANCE_URL/extensions/marketplace_extension_api_explorer::api-explorer/

  • 如果您的 Looker 实例没有 API Explorer，您可以从 Looker Marketplace 安装它。如需了解相关信息，请参阅使用 API Explorer 页面。

如需注册扩展程序，请完成以下步骤：

  1. 按照注册 OAuth 客户端应用文档中的说明注册扩展程序。

  2. 对于 client_guid 字段，请完成以下步骤：

    • 使用任何全局唯一 ID。
    • 请准备好将 ID 分发给任何想要使用该扩展程序的 LookML 开发者。

  3. 对于 redirect_uri，请使用：

    vscode://google.vscode-looker-official/oauth_callback

  4. 按照注册 OAuth 客户端应用文档中的说明完成 display_name 和 description。

应用注册后，API Explorer 将返回包含注册摘要的响应。您可以使用 Get OAuth Client App 端点和 client_guid 来查看注册详细信息。

将生成的 client_guid 提供给开发者；他们将在配置扩展程序时使用该令牌。

安装扩展程序

如需安装扩展程序，请完成以下步骤：

  1. 从 Visual Studio Marketplace 安装适用于 VS Code 的 Looker 扩展程序。
  2. 打开您的 IDE，例如 VS Code 或 Cursor。
  3. 点击活动栏中的扩展程序图标。
  4. 找到 Looker 扩展程序（适用于 VS Code），然后点击安装。
  5. 安装扩展程序后， Looker 图标会显示在活动栏中。

配置扩展程序

您必须在工作区的 settings.json 文件中配置扩展程序，并提供 Looker 实例详细信息。

  1. 在工作区处于打开状态时，打开命令面板（在 Mac 上按 Command-Shift-P，在 Windows/Linux 上按 Ctrl+Shift+P）。
  2. 搜索并选择 Preferences: Open Workspace Settings (JSON)。
  3. 将配置变量添加到设置中。配置变量会因您的身份验证方法是 OAuth 还是 API 凭据而异。

建议使用 OAuth 2.1 身份验证流程。将这些设置粘贴到工作区 settings.json 文件中。

{
  "looker.instanceUrl": "https://YOUR_INSTANCE_URL",
  "looker.oauthClientId": "YOUR_OAUTH_CLIENT_ID",
  "looker.projectId": "YOUR_PROJECT_ID"
}

替换以下内容：

  • https://YOUR_INSTANCE_URL：Looker 实例的网址。
  • YOUR_OAUTH_CLIENT_ID：您从 Looker 管理员处获得的 OAuth 客户端 ID (client_guid)。
  • YOUR_PROJECT_ID：要修改的项目的名称。如需查找该文件，请在 Looker 实例中打开 LookML 项目页面。项目 ID 位于项目列中。

使用 API 凭据进行身份验证

如果您想使用 Looker API 密钥，请按照文档创建 API 凭据。您还必须提供项目 ID。

{
  "looker.instanceUrl": "https://YOUR_INSTANCE_URL",
  "looker.clientId": "YOUR_CLIENT_ID",
  "looker.clientSecret": "YOUR_CLIENT_SECRET",
  "looker.projectId": "YOUR_PROJECT_ID"
}

替换以下内容：

  • https://YOUR_INSTANCE_URL：Looker 实例的网址。
  • YOUR_CLIENT_ID 和 YOUR_CLIENT_SECRET：您用于进行身份验证的 API 凭据的客户端 ID 和客户端密钥。如需查找这些凭据，请在 Looker 实例中打开账号页面；然后，在 API 密钥部分中，点击管理按钮。这会打开 API 密钥页面，您可以在其中查看客户端 ID 和密钥。
  • YOUR_PROJECT_ID：要修改的项目的名称。如需查找项目名称，请在 Looker 实例中打开 LookML 项目页面。项目 ID 位于项目列中。

设置

您可以在 IDE 工作区中配置以下 MCP 设置。

设置 说明 默认
looker.instanceURL Looker 实例的基础网址（例如 https://mycompany.looker.com）。 -
looker.authURL 用于 OAuth 身份验证的网址。仅当与您的实例网址不同时才设置。 looker.instanceURL
looker.sdkURL 用于 API 请求的网址。仅当与实例网址不同时才设置。 looker.instanceURL
looker.oauthClientId Looker OAuth 客户端 ID。OAuth 所需。 -
looker.clientId Looker API 客户端 ID。对于 API 密钥身份验证，此参数为必需参数。 -
looker.clientSecret Looker API 客户端密钥。对于 API 密钥身份验证，此参数为必需参数。 -
looker.projectId Looker 项目 ID。 -
looker.mcpServerUrl 要代理的外部 MCP 服务器的网址（例如 http://localhost:5000/mcp）。 -
looker.acceptSelfSignedCertificates 忽略 SSL 证书错误（例如，对于自签名证书）。警告：不建议启用此选项。 false
looker.askBeforeOverwritingRemote 检测到冲突时，在覆盖远程文件之前始终询问。 false

通过 Looker 进行身份验证

如果您使用的是 OAuth 身份验证，则必须登录才能将本地 IDE 关联到您的 Looker 账号。

  1. 打开命令面板。
  2. 运行命令：Looker：登录 (OAuth)。
  3. 确认提示以打开浏览器。
  4. 在浏览器中，授权该扩展程序访问您的 Looker 账号。
  5. 授权后，浏览器会重定向回您的 IDE。您应该会看到一条通知，告知您已成功登录 Looker！

克隆 LookML 项目

若要开始开发，您必须将 LookML 代码库克隆到本地机器。

  1. 在 VS Code 中，打开一个新窗口。
  2. 打开命令面板，然后选择 Git：克隆。
  3. 输入远程 Git 代码库（例如 GitHub 或 GitLab 中的代码库）的网址，然后选择一个本地文件夹。
  4. 在 IDE 中打开已克隆的文件夹。

该扩展程序会自动检测 LookML 文件，并开始与 Looker 实例的开发模式中已签出的分支进行同步。

问题排查

您可以在 IDE 的输出面板中查看扩展程序日志。选择 Looker 渠道以查看日志。如需获取更详细的日志，请打开命令面板，运行 Developer: Set Log Level 命令，然后选择 Debug 或 Trace。

  • 身份验证错误：验证您的 looker.instanceUrl 和 looker.oauthClientId 是否正确。确保 Looker 中的重定向 URI 完全一致。
  • 同步问题：检查扩展程序日志以解决同步问题。如需查看日志，请打开输出面板，然后从下拉菜单中选择 Looker。
  • OAuth 期间出现“错误请求”响应：确保您的 Looker 实例可从本地网络访问，并且您有有效的互联网连接。

如果您在使用扩展程序时遇到问题，可以从命令面板运行 Developer: Reload Window 命令来解决这些问题。

后续步骤