使用Firestore REST API与本地模拟器创建文档返回404：路径参数问题

问题背景 #

作为入门开发者，正在学习Firebase/Firestore，为朋友的项目编写可调用函数的集成测试，使用Firebase本地模拟器做自动化测试。已成功通过POST请求创建认证用户并获取userIdToken和userLocalId，但发送创建Firestore文档的POST请求时返回404错误。

创建用户的代码（无问题）：

interface CreatePostRequest {
  url: string;
  data: Record<string, any>;
  config: { headers: Record<string, string> };
};

// 创建用户实例
const createUserInstance: CreatePostRequest = {
  url: 'http://localhost:9099/identitytoolkit.googleapis.com/v1/accounts:signUp?key=hi',
  data: {
    email: 'myemail@email.com',
    password: 'mypassword',
    returnSecureToken: true
  },
  config: {
    headers: { 'Content-Type': 'application/json' }
  },
};
const createUserResponse = await axios.post(createUserInstance.url, createUserInstance.data, createUserInstance.config);

const userIdToken = createUserResponse.data.idToken;
const userLocalId = createUserResponse.data.localId;

错误的创建文档代码：

const createDocumentInstance: CreatePostRequest = {
  url: "https://firestore.googleapis.com/v1beta1/projects/'localhost:8080/okane-crud-dev'/databases/(default)/documents/test",
  data: {
    "fields": {
      "localId": userLocalId,
      'budget': '2000',
    }
  },
  config: {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${userIdToken}`,
    }
  }
};
const createDocument = await axios.post(createDocumentInstance.url, createDocumentInstance.data, createDocumentInstance.config);

返回错误：

Request failed with status code 404

at createError (../../node_modules/axios/lib/core/createError.js:16:15)
at settle (../../node_modules/axios/lib/core/settle.js:17:12)
at IncomingMessage.handleStreamEnd (../../node_modules/axios/lib/adapters/http.js:293:11)

核心错误原因 #

1. URL格式完全错误：本地Firestore模拟器的API地址是http://localhost:8080，不能使用谷歌官方域名firestore.googleapis.com；项目ID直接写okane-crud-dev，不需要嵌套localhost:8080。
2. 请求体字段格式不符合要求：Firestore REST API的fields必须是带类型的结构（比如字符串用stringValue，数字用integerValue），不能直接传原始值。
3. 多余的引号嵌套：URL里的'localhost:8080/okane-crud-dev'属于错误写法，导致路径解析失败。

修正后的代码 #

const createDocumentInstance: CreatePostRequest = {
  // 修正后的本地模拟器URL
  url: 'http://localhost:8080/v1/projects/okane-crud-dev/databases/(default)/documents/test',
  data: {
    fields: {
      // 按照Firestore REST API要求的字段格式
      localId: { stringValue: userLocalId },
      budget: { integerValue: '2000' } // 数字类型用integerValue，值为字符串格式
    }
  },
  config: {
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${userIdToken}` // 变量可以正常使用，之前的引号问题是转义错误
    }
  }
};

console.log(createDocumentInstance);
const createDocument = await axios.post(createDocumentInstance.url, createDocumentInstance.data, createDocumentInstance.config); 
const docReference = createDocument.data;
console.log(docReference);

额外注意事项 #

• 确认Firestore模拟器在8080端口运行：启动模拟器时会显示端口信息，若端口不同需对应修改URL。
• 如果需要指定文档ID，将URL改为http://localhost:8080/v1/projects/okane-crud-dev/databases/(default)/documents/test/{your-document-id}，同时使用PUT请求。
• 接口类型CreatePostRequest建议明确类型，比如用Record<string, any>代替Object，避免类型模糊。

内容的提问来源于stack exchange，提问作者flythejet