Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

Looker 扩展程序 for VS Code 不支持非 VS Code 分叉的 IDE，例如 IntelliJ 和 Eclipse。

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

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 服务器，例如 Looker 管理的 MCP 服务器。

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

准备工作

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

连接到 AI 工具：如果您打算使用 AI 辅助开发，请将 IDE 和 AI 智能体连接到 Looker 管理的 MCP 服务器。设置和配置示例显示在 Looker 管理的 MCP 服务器文档页面上。如需了解更多详情，请参阅工具的文档。
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：

已安装 API Explorer

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

LOOKER_INSTANCE_URL/extensions/marketplace_extension_api_explorer::api-explorer/

未安装 API Explorer

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

PSA 专用实例

如果您使用的是采用专用服务访问通道的 Looker (Google Cloud Core) 私密连接实例，则不支持 Looker Marketplace 和 API Explorer。如需注册 AI 智能体，您必须直接调用 oauth_client_apps API 端点。如果您使用此方法，则可以跳过此 API Explorer 程序的其余步骤。

以下示例展示了如何使用 curl 命令和 oauth_client_apps 端点注册代理。

curl -X POST "https://LOOKER_INSTANCE_URL/api/4.0/oauth_client_apps/CLIENT_GUID" \
-H "Authorization: token ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "redirect_uri": "REDIRECT_URI",
  "display_name": "CLIENT_NAME",
  "description": "OAuth client to access MCP server using CLIENT_NAME",
  "enabled": true
}'

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

按照注册 OAuth 客户端应用文档中的说明注册扩展程序。
对于 client_guid 字段，请完成以下步骤：
- 使用任何全局唯一 ID。
- 准备好将 ID 分发给任何想要使用该扩展程序的 LookML 开发者。

对于 redirect_uri，请输入 IDE 的回调网址。根据您的 IDE 或编码工具，使用以下回调网址之一：

IDE 或工具	回调网址
VS Code	vscode://google.vscode-looker-official/oauth_callback
Antigravity	antigravity://google.vscode-looker-official/oauth_callback
Code-OSS	code-oss://google.vscode-looker-official/oauth_callback
光标	cursor://google.vscode-looker-official/oauth_callback
HTTPS	https://google.vscode-looker-official/oauth_callback
Looker	looker://google.vscode-looker-official/oauth_callback
Windsurf	windsurf://google.vscode-looker-official/oauth_callback

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

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

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

安装扩展程序

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

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

配置扩展程序

您可以在工作区的 settings.json 文件、直观的 VS Code 设置编辑器（偏好设置：打开工作区设置）或 Looker 扩展程序的互动式初始配置界面中，使用 Looker 实例详细信息配置该扩展程序。

以下步骤演示了如何修改 settings.json 文件（以该文件为例）。如果您改用 VS Code 设置编辑器或 Looker 扩展程序的界面，也能实现相同效果。

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

使用 OAuth 进行身份验证（推荐）

建议使用 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`

配置 MCP 客户端

如需让 AI 智能体通过扩展程序与 Looker 互动，您必须将智能体配置为连接到扩展程序的 MCP 代理网址。默认情况下，代理在本地运行，网址为 http://127.0.0.1:5050。

如果您的 MCP 服务器在 5000 以外的端口上运行，或者在远程机器上运行，您必须更新扩展程序的代理配置。为此，请更新 VS Code 工作区设置中的 looker.mcpServerUrl 设置。如需了解详情，请参阅设置部分。

Visual Studio Code (Copilot)

打开 VS Code，并在项目根目录中创建 .vscode 目录（如果尚不存在）。
创建 .vscode/mcp.json 文件（如果尚不存在），并打开该文件。
添加以下配置并保存文件：

      {
        "servers": {
          "looker": {
            "type": "http",
            "url": "http://127.0.0.1:5050"
          }
        }
      }

Claude Code

在项目根目录中创建 .mcp.json 文件（如果尚不存在）。
添加以下配置并保存文件：

      {
        "mcpServers": {
          "looker": {
            "type": "http",
            "url": "http://127.0.0.1:5050"
          }
        }
      }

光标

在项目根目录中创建 .cursor 目录（如果尚不存在）。
创建 .cursor/mcp.json 文件（如果尚不存在），并打开该文件。
添加以下配置并保存文件：

      {
        "mcpServers": {
          "looker": {
            "type": "http",
            "url": "http://127.0.0.1:5050"
          }
        }
      }

打开 Cursor，然后依次前往设置 > Cursor 设置 > MCP。服务器连接时，系统会显示绿色的活跃状态。

Cline

在 VS Code 中打开 Cline 扩展程序，然后点击 MCP 服务器图标。
点击配置 MCP 服务器以打开配置文件。
添加以下配置并保存文件：

      {
        "mcpServers": {
          "looker": {
            "type": "http",
            "url": "http://127.0.0.1:5050"
          }
        }
      }

Windsurf

打开 Windsurf 并前往 Cascade 助理。
点击 MCP 图标，然后点击配置以打开配置文件。
添加以下配置并保存文件：

      {
        "mcpServers": {
          "looker": {
            "type": "http",
            "url": "http://127.0.0.1:5050"
          }
        }
      }

通过 Looker 进行身份验证

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

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

克隆 LookML 项目

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

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

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

问题排查

您可以在 IDE 的输出面板中查看扩展程序日志。选择 Looker 渠道即可查看日志。如需查看更详细的日志，请打开命令面板，运行开发者：设置日志级别命令，然后选择调试或跟踪。

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

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