用 Project IDX 从模板创建并运行一个全栈云端项目

Project IDX 是 Google 提供的云端开发环境，构建在 VS Code 之上，把编辑器、终端、依赖安装、应用预览和 AI 助手一起搬到浏览器里。它要解决的问题很具体：不想在本地装 Node.js、数据库、模拟器，也不想为了验证一个想法花半天配环境。适合的人群包括做快速原型验证的开发者、教学与学习场景、需要多人协作同一份环境的团队，以及临时借用他人设备写代码的人。它不适合必须访问本地硬件、对延迟极其敏感、或需要完全离线工作的项目。站内关于这个工具的条目见 Project IDX。

下面按实际操作顺序展开：先说明账号与前置条件，再逐步创建项目、认识界面、调用 AI 助手、自定义环境、接入 Git、使用预览窗口，最后给出一个从头到尾能跑通的最小示例，以及素材中提到的限制与常见坑。

准备工作

账号与登录

• 需要一个 Google 账号。Project IDX 通过 Google 账号登录，没有独立的注册流程。
• 首次进入时需要同意服务条款，这一步只做一次。
• 如果打算从 GitHub 导入已有仓库，提前准备好对应的 GitHub 账号，并确认对目标仓库有访问权限。

浏览器与网络

• Project IDX 是纯云端服务，所有编辑、构建、预览都在远端完成，因此必须保持网络连接。素材明确说明它不能离线使用。
• 使用较新的桌面浏览器访问，移动端浏览器不适合作为主要开发界面。
• 由于工作区在云端，网络抖动会直接影响编辑与预览的响应，选择稳定的网络环境能明显改善体验。

不需要在本地安装的东西

这是 Project IDX 与本地 VS Code 最大的差别。使用本地编辑器时，你需要自己安装 Node.js、包管理器、数据库、移动端模拟器等依赖；在 Project IDX 里，这些由模板或自定义的开发容器镜像提供。因此准备工作里不需要列本地环境清单，只需要确认账号、网络和要用的代码仓库。

关于费用

素材提到该产品在测试阶段可以免费使用，并提到未来可能推出付费计划。这类信息变动频繁，具体额度、可用地区与计费方式请以官网当前信息为准，不要按本文的描述做预算判断。

操作步骤

第一步：登录并进入工作区列表

用浏览器打开 Project IDX，使用 Google 账号登录，同意服务条款后进入工作区列表页。这个页面是你所有云端项目的入口，已创建的工作区会在这里列出，可以随时重新打开继续编辑。

第二步：创建新项目

在工作区列表页点击 New Workspace，会看到一组项目模板。素材列出的模板类型如下：

模板	内容
Full-stack Web App	全栈 Web 应用，Next.js + PostgreSQL
Frontend Web App	前端应用，可选 React、Vue、Angular
Mobile App	移动应用，可选 Flutter、React Native
Python App	Python 应用，可选 FastAPI、Flask
Go App	Go 应用
Blank Template	空白模板，从零开始

选择模板后，环境会按模板预置的镜像和依赖自动准备。如果已有代码，也可以选择从 GitHub 导入现有项目，而不是从模板起步。

选择模板时的一个实用判断标准：如果你要验证的是「页面长什么样」，选前端或移动模板；如果要验证「接口能不能跑通」，选 Python 或 Go 模板；如果前后端都要，选全栈模板，它自带 PostgreSQL，省去单独配数据库的步骤。

第三步：熟悉开发界面

工作区打开后，界面布局与 VS Code 高度相似，主要区域划分如下：

• 左侧边栏：文件浏览器、搜索、Git、扩展等面板入口。
• 中央区域：代码编辑器，支持多文件标签页。
• 右侧面板：AI 助手（Gemini）、终端、预览窗口。
• 底部状态栏：运行状态、当前 Git 分支、通知。

因为布局沿用 VS Code 的习惯，熟悉 VS Code 的人几乎不需要学习成本；不熟悉的人也可以按「左边找文件、中间写代码、右边看结果和问 AI」来记。

第四步：使用 Gemini AI 助手

点击右侧的 Gemini 图标打开 AI 助手面板。素材给出的四类典型用法是：

• 生成代码：例如输入「创建一个用户登录表单，包含邮箱和密码验证」。
• 解释代码：选中一段代码后问「这段代码做了什么？」。
• 调试问题：把报错信息粘贴进去，问「这个错误怎么解决？」。
• 重构代码：问「如何优化这段代码的性能？」。

素材中的一段示例对话可以说明交互节奏：先让助手生成一个显示用户列表、支持搜索和分页的 React 组件，助手返回完整代码；再追加一句「添加 TypeScript 类型定义」，助手在已有代码基础上补充接口定义。这种「先出骨架、再逐步加约束」的方式比一次性描述全部需求更容易得到可用的结果。

使用 AI 助手时值得注意的一点：它生成的是建议代码，仍然需要你自己运行、验证、调整。把它当作一个能读懂当前工作区上下文的协作者，而不是替代测试的工具。

第五步：用 .devcontainer.json 自定义开发环境

模板提供的是默认环境。当项目需要额外的系统工具、CLI 或编辑器扩展时，通过工作区根目录下的 .devcontainer.json 声明。素材给出的示例结构如下：

{
  "name": "My Custom Dev Environment",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:18",
  "features": {
    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ]
    }
  }
}

这个文件里几个字段的作用分别是：

• name：环境名称，用于标识这个开发容器。
• image：基础镜像，决定预装的语言运行时。示例用的是 Node 18 的 TypeScript 镜像。
• features：在基础镜像之上叠加的能力。示例加了 Docker-in-Docker 和 GitHub CLI。
• customizations.vscode.extensions：环境启动时自动安装的编辑器扩展，示例是 ESLint 与 Prettier。

把扩展写进这个文件而不是每次手动安装，好处是环境可复现：换一台设备、换一个协作者，打开工作区就是同一套工具链。

第六步：接入 Git

Project IDX 内置 Git 支持，日常操作不需要回到命令行：

• 在左侧 Git 面板查看当前变更。
• 直接提交并推送代码。
• 创建和合并分支。
• 查看提交历史。

底部状态栏会显示当前分支，切换分支后可以据此确认自己处在正确的上下文里，避免把改动提交到错误的分支。

第七步：安装扩展

扩展的安装方式与 VS Code 一致：点击左侧扩展图标，搜索需要的扩展，点击安装。素材推荐的常用扩展包括：

• ESLint：代码检查。
• Prettier：代码格式化。
• GitLens：Git 增强，查看行级提交信息。
• Thunder Client：接口测试。
• Docker：容器管理。

如果某个扩展是项目必需的，建议同时写进 .devcontainer.json 的扩展列表，这样新环境打开时自动装好。

第八步：使用预览窗口

右侧面板内置应用预览窗口，支持 Web 以及 iOS、Android 多端模拟。对全栈项目，素材提到可以同时打开多个预览窗口：一侧看前端界面，一侧看 API 文档，底部看数据库状态。这样在改一处代码后，能同时确认页面和接口两侧的表现。

一个完整示例

下面用一个最小但完整的流程，把前面的步骤串起来：从模板创建一个全栈项目，用 AI 助手补一个页面，自定义环境，接入 Git，最后在预览窗口确认结果。

1. 创建全栈工作区

登录后点击 New Workspace，选择 Full-stack Web App 模板（Next.js + PostgreSQL）。等待环境准备完成，工作区自动打开。

2. 确认项目结构

在左侧文件浏览器里浏览项目目录，确认页面目录、接口目录和数据库配置的位置。这一步不需要改代码，目的是知道后面 AI 生成的代码应该落在哪里。

3. 用 AI 生成第一个页面

打开右侧 Gemini 面板，输入类似这样的请求：

创建一个文章列表页面，从数据库读取文章标题和摘要，支持按标题搜索，列表分页显示。

助手会返回组件代码。把代码放进对应的页面文件，然后追加一句要求类型定义：

为文章数据添加 TypeScript 类型定义。

助手会在已有代码基础上补充接口定义。此时不要急着继续加功能，先运行起来看结果。

4. 自定义环境

在项目根目录创建 .devcontainer.json，写入需要的镜像、features 和扩展。例如需要 Docker 和 GitHub CLI 时，按前文的示例结构声明；需要 ESLint 与 Prettier 时，把扩展 ID 加进 customizations.vscode.extensions。保存后环境会按新配置重建。

5. 提交代码

打开左侧 Git 面板，确认变更列表里只有你预期的文件，填写提交信息，提交并推送。如果还没有远端仓库，先在 GitHub 上创建，再关联推送。底部状态栏确认当前分支正确。

6. 在预览窗口验证

打开右侧预览窗口，加载应用。检查三件事：页面能否正常渲染、搜索框输入后列表是否按预期过滤、分页切换是否正常。如果报错，把错误信息复制到 Gemini 面板询问原因，按建议修改后重新预览。

7. 分享预览链接

素材提到可以部署预览并分享链接，用于让其他人查看运行结果。分享前确认链接指向的是你希望对方看到的那次构建。

注意事项

必须联网

Project IDX 是纯云端服务，没有离线模式。网络不可用时无法编辑、构建或预览。需要完全离线工作的场景不适合使用它。

不适合访问本地硬件

依赖本地 USB 设备、串口、特定硬件驱动的项目，在云端环境里无法直接调试。素材把「需要访问本地硬件的项目」列为不适用场景。

延迟敏感型开发

所有操作都在远端执行，本地只负责显示。对输入延迟、构建反馈时间极其敏感的工作流，体验会不如本地环境。

敏感数据的处理

代码存储在云端。素材提到平台提供私有工作空间并符合相关安全标准，但同时建议涉及高度敏感数据的项目谨慎使用云端环境。是否把某类数据放进云端工作区，需要按所在组织的合规要求自行判断。

免费额度与计费

测试阶段的免费状态、未来的付费计划、各地区可用性都可能变化。任何涉及价格、配额、地区可用性的决策，请以官网当前信息为准。

AI 生成代码需要验证

Gemini 助手生成的代码是起点而非终点。生成后要运行、要测试、要按项目规范调整。尤其是涉及数据读写、鉴权、输入校验的部分，不能仅凭生成结果就认为可用。

扩展与环境的可复现性

手动安装的扩展只存在于当前工作区。如果项目需要多人协作或需要重建环境，把扩展和系统依赖写进 .devcontainer.json，否则换一个工作区就要重新配一遍。

模板只是起点

模板预置的框架和数据库组合是常见搭配，不等于项目最终需要的技术栈。选模板时按验证目标选，后续再按实际需求调整依赖，不要为了贴合模板而改变技术选型。