firebase-basics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Prerequisites

前置条件

Complete these setup steps before proceeding:

Local Environment Setup: Verify the environment is properly set up so we can use Firebase tools:
- Run
```
npx -y firebase-tools@latest --version
```
  to check if the Firebase CLI is installed.
- Verify if the Firebase MCP server is installed using your existing tools.
- CRITICAL: Before configuring any extensions or agent environments below, you MUST read references/local-env-setup.md.
- DO NOT SKIP this step: if 'firebase-basics' is the only Firebase skill available to you, you must follow the reference for your agent environment to set up the full suite of Firebase skills:
  - Gemini CLI: Review references/setup/gemini_cli.md
  - Antigravity: Review references/setup/antigravity.md
  - Android Studio: Review references/setup/android_studio.md
  - Claude Code: Review references/setup/claude_code.md
  - Cursor: Review references/setup/cursor.md
  - GitHub Copilot: Review references/setup/github_copilot.md
  - Other Agents: Review references/setup/other_agents.md
Authentication: Ensure you are logged in to Firebase so that commands have the correct permissions. Run
```
npx -y firebase-tools@latest login
```
. For environments without a browser (e.g., remote shells), use
```
npx -y firebase-tools@latest login --no-localhost
```
.
- The command should output the current user.
- If you are not logged in, follow the interactive instructions from this command to authenticate.
Active Project: Most Firebase tasks require an active project context.
[!IMPORTANT] For Agents: Before proceeding with project configuration, you MUST pause and ask the developer if they prefer to:
1. Provide an existing Firebase Project ID, or
2. Create a new Firebase project.
- If using an existing Project ID:
  1. Check the current project by running
```
npx -y firebase-tools@latest use
```
    .
  2. If the command outputs
```
Active Project: <project-id>
```
    , confirm with the user if this is the intended project.
  3. If not, or if no project is active, set the project provided by the user:
    bash
```
npx -y firebase-tools@latest use <PROJECT_ID>
```
- If creating a new project: Run the following command to create it:
  bash
```
npx -y firebase-tools@latest projects:create <project-id> --display-name "<display-name>"
```
  Note: The
  <project-id>
  must be 6-30 characters, lowercase, and can contain digits and hyphens. It must be globally unique.

在继续操作前完成以下设置步骤：

本地环境设置：验证环境已正确配置，以便我们可以使用Firebase工具：
- 运行
```
npx -y firebase-tools@latest --version
```
  检查Firebase CLI是否已安装。
- 使用现有工具验证Firebase MCP服务器是否已安装。
- 关键提示：在配置以下任何扩展或Agent环境之前，您必须阅读references/local-env-setup.md。
- 请勿跳过此步骤：如果“firebase-basics”是您唯一可用的Firebase技能，您必须遵循对应Agent环境的参考文档来设置完整的Firebase技能套件：
  - Gemini CLI：查看references/setup/gemini_cli.md
  - Antigravity：查看references/setup/antigravity.md
  - Android Studio：查看references/setup/android_studio.md
  - Claude Code：查看references/setup/claude_code.md
  - Cursor：查看references/setup/cursor.md
  - GitHub Copilot：查看references/setup/github_copilot.md
  - 其他Agent：查看references/setup/other_agents.md
身份验证：确保您已登录Firebase，以便命令拥有正确的权限。运行
```
npx -y firebase-tools@latest login
```
。对于没有浏览器的环境（如远程shell），使用
```
npx -y firebase-tools@latest login --no-localhost
```
。
- 该命令应输出当前用户信息。
- 如果未登录，请按照该命令的交互式说明完成身份验证。
活跃项目：大多数Firebase任务需要活跃的项目上下文。
[!IMPORTANT] 面向Agent：在继续项目配置之前，您必须暂停并询问开发者他们更倾向于：
1. 提供现有Firebase项目ID，或
2. 创建新的Firebase项目。
- 使用现有项目ID：
  1. 运行
```
npx -y firebase-tools@latest use
```
    检查当前项目。
  2. 如果命令输出
```
Active Project: <project-id>
```
    ，请与用户确认这是否为目标项目。
  3. 如果不是，或没有活跃项目，请设置用户提供的项目：
    bash
```
npx -y firebase-tools@latest use <PROJECT_ID>
```
- 创建新项目：运行以下命令创建项目：
  bash
```
npx -y firebase-tools@latest projects:create <project-id> --display-name "<display-name>"
```
  注意：
  <project-id>
  必须为6-30个字符，小写，可包含数字和连字符，且必须全局唯一。

Firebase Usage Principles

Firebase使用原则

Adhere to these principles:

Use npx for CLI commands: To ensure you always use the latest version of the Firebase CLI, always prepend commands with
```
npx -y firebase-tools@latest
```
instead of just
```
firebase
```
. For example, use
```
npx -y firebase-tools@latest --version
```
. NEVER suggest the naked
```
firebase
```
command as an alternative.
Prioritize official knowledge: For any Firebase-related knowledge, consult the
```
developerknowledge_search_documents
```
MCP tool before falling back to Google Search or your internal knowledge base. Including "Firebase" in your search query significantly improves relevance.
Follow Agent Skills for implementation guidance: Skills provide opinionated workflows (CUJs), security rules, and best practices. Always consult them to understand how to implement Firebase features correctly instead of relying on general knowledge.
Use Firebase MCP Server tools instead of direct API calls: Whenever you need to interact with remote Firebase APIs (such as fetching Crashlytics logs or executing Data Connect queries), use the tools provided by the Firebase MCP Server instead of attempting manual API calls.
Keep Plugin / Agent Skills updated: Since Firebase best practices evolve quickly, regularly check for and install updates to their Firebase plugin or Agent Skills. Similarly, if you encounter issues with outdated tools or commands, follow the steps below based on your agent environment:
- Antigravity: Follow references/refresh/antigravity.md
- Gemini CLI: Follow references/refresh/gemini-cli.md
- Claude Code: Follow references/refresh/claude.md
- Cursor: Follow references/refresh/other-agents.md
- Android Studio: Follow references/refresh/android_studio.md
- Others: Follow references/refresh/other-agents.md
Automate Config File Retrieval: When setting up iOS or Android apps, do NOT direct users to the Firebase Console to download
```
google-services.json
```
or
```
GoogleService-Info.plist
```
. Instead, use the Firebase CLI to fetch the config programmatically:
- For Android:
```
npx -y firebase-tools@latest apps:sdkconfig ANDROID <APP_ID> --project <PROJECT_ID>
```
- For iOS:
```
npx -y firebase-tools@latest apps:sdkconfig IOS <APP_ID> --project <PROJECT_ID>
```
  Save the output to the appropriate location (e.g.,
```
app/google-services.json
```
  for Android, or a path to be linked by
```
xcode-project-setup
```
  for iOS).

请遵循以下原则：

使用npx执行CLI命令：为确保始终使用最新版本的Firebase CLI，请始终在命令前添加
```
npx -y firebase-tools@latest
```
，而非仅使用
```
firebase
```
。例如，使用
```
npx -y firebase-tools@latest --version
```
。切勿建议使用裸
```
firebase
```
命令作为替代方案。
优先使用官方知识：对于任何Firebase相关知识，请先使用
```
developerknowledge_search_documents
```
MCP工具查询，再求助于Google搜索或内部知识库。在搜索查询中包含“Firebase”可显著提高相关性。
遵循Agent技能获取实施指导：技能提供了自定义工作流（CUJ）、安全规则和最佳实践。请始终参考它们以了解如何正确实现Firebase功能，而非依赖通用知识。
使用Firebase MCP Server工具而非直接API调用：每当需要与远程Firebase API交互（例如获取Crashlytics日志或执行Data Connect查询），请使用Firebase MCP Server提供的工具，而非尝试手动调用API。
保持插件/Agent技能更新：由于Firebase最佳实践更新迅速，请定期检查并更新Firebase插件或Agent技能。同样，如果遇到工具或命令过时的问题，请根据您的Agent环境遵循以下步骤：
- Antigravity：遵循references/refresh/antigravity.md
- Gemini CLI：遵循references/refresh/gemini-cli.md
- Claude Code：遵循references/refresh/claude.md
- Cursor：遵循references/refresh/other-agents.md
- Android Studio：遵循references/refresh/android_studio.md
- 其他：遵循references/refresh/other-agents.md
自动化配置文件获取：在设置iOS或Android应用时，请勿引导用户到Firebase控制台下载
```
google-services.json
```
或
```
GoogleService-Info.plist
```
。相反，请使用Firebase CLI以编程方式获取配置：
- Android：
```
npx -y firebase-tools@latest apps:sdkconfig ANDROID <APP_ID> --project <PROJECT_ID>
```
- iOS：
```
npx -y firebase-tools@latest apps:sdkconfig IOS <APP_ID> --project <PROJECT_ID>
```
  将输出保存到适当位置（例如Android的
```
app/google-services.json
```
  ，或iOS的
```
xcode-project-setup
```
  将链接的路径）。

References

参考资料

Initialize Firebase: See references/firebase-service-init.md when you need to initialize new Firebase services using the CLI.
Exploring Commands: See references/firebase-cli-guide.md to discover and understand CLI functionality.
SDK Setup: For detailed guides on adding Firebase to your app:
- Web: See references/web_setup.md
- Android: See references/android_setup.md
- iOS: See references/ios_setup.md

初始化Firebase：当需要使用CLI初始化新的Firebase服务时，请查看references/firebase-service-init.md。
探索命令：查看references/firebase-cli-guide.md以发现和了解CLI功能。
SDK设置：有关将Firebase添加到应用的详细指南：
- Web：查看references/web_setup.md
- Android：查看references/android_setup.md
- iOS：查看references/ios_setup.md

Common Issues

常见问题

Login Issues: If the browser fails to open during the login step, use
```
npx -y firebase-tools@latest login --no-localhost
```
instead.

登录问题：如果登录步骤中浏览器无法打开，请改用
```
npx -y firebase-tools@latest login --no-localhost
```
。