React+TS项目部署Netlify后Mapbox API报401未授权错误

DevOps 小满

2026-9-1

问题描述

技术栈：React JS + TypeScript
故障场景：项目部署至Netlify后Mapbox位置搜索功能失效，本地开发环境运行完全正常
运行时报错信息：
- 控制台输出：Failed to load resource: the server responded with a status of 401 (Unauthorized)
- 故障特征：Mapbox接口请求地址中access_token参数值为undefined，接口返回响应内容为{"message": "Not Authorized - Invalid Token"}
本地环境变量配置（.env文件）：

REACT_APP_ACESS_TOKEN_MAP_BOX=pk.（实际本地为完整pk开头的Mapbox公钥）
REACT_APP_API_URL=http://localhost:（实际本地为完整本地服务地址）

核心业务代码：

import axios from "axios";
import { OrderPayload } from "./Orders/types";

const API_URL = process.env.REACT_APP_API_URL;
const mapboxToken = process.env.REACT_APP_ACESS_TOKEN_MAP_BOX;

export function fetchProducts (){
    return axios(`${API_URL}/products`)
}

export function fetchLocalMapBox(local: string){
    return axios (`https://api.mapbox.com/geocoding/v5/mapbox.places/${local}.json?access_token=${mapboxToken}`)
}

export function saveOrder(payload: OrderPayload) {
    return axios.post(`${API_URL}/orders`, payload);
}

故障原因

核心原因是Netlify构建环境未正确注入对应环境变量，具体逻辑：

Create React App脚手架在生产构建时，只会将代码中引用到的、以REACT_APP_开头的环境变量静态替换进打包产物，不会主动读取本地项目里的.env文件——这类本地文件不会随代码上传到Netlify构建环境，自然读不到值。
请求里access_token为undefined，就是构建时没拿到对应环境变量值，直接把process.env.REACT_APP_ACESS_TOKEN_MAP_BOX替换成了undefined。
额外注意点：当前变量名存在拼写错误（正确拼写应为ACCESS，现有写法为ACESS，少了第二个C），如果Netlify后台配置时拼对了单词、和代码里的变量名不匹配，也会导致读取失败。

解决步骤

进入Netlify对应项目的管理后台，找到「站点设置 - 构建与部署 - 环境变量」配置页
添加2个生产环境变量，变量名必须和代码里的写法完全一致，大小写、拼写不能有偏差：
- 键：REACT_APP_ACESS_TOKEN_MAP_BOX，值：填写完整的Mapbox公钥（pk开头的完整字符串，不要截断）
- 键：REACT_APP_API_URL，值：填写线上后端服务的可访问地址，不要填本地localhost地址（线上环境无法访问本地服务端口）
保存配置后，手动触发一次重新部署（Netlify后台部署列表里点「重试部署」即可，不需要修改代码）
部署完成后清空浏览器缓存访问线上站点，检查Mapbox接口请求里的access_token参数是否已带上正确值，功能即可恢复。

优化建议

建议统一修正变量名的拼写错误：把代码、本地.env、Netlify后台的REACT_APP_ACESS_TOKEN_MAP_BOX改成正确的REACT_APP_ACCESS_TOKEN_MAP_BOX，避免后续维护时因为拼写偏差踩同类坑。
可以在代码入口处加环境变量校验，构建/启动时如果缺少必要变量直接抛出明确错误，避免上线后才发现配置问题：

const requiredEnvs = [
  "REACT_APP_API_URL",
  "REACT_APP_ACESS_TOKEN_MAP_BOX"
] as const;

requiredEnvs.forEach(envKey => {
  if (!process.env[envKey]) {
    throw new Error(`缺少必要环境变量：${envKey}，请检查配置后重新启动/构建`);
  }
});

const API_URL = process.env.REACT_APP_API_URL;
const mapboxToken = process.env.REACT_APP_ACESS_TOKEN_MAP_BOX;

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