Expo SDK49本地与GitHub Actions中TypeScript类型报错差异求助

本地与CI环境类型检查差异的原因 #

本地执行tsc --noEmit --pretty时，会读取.expo/types/router.d.ts——这是Expo Router在本地开发过程中根据你的项目路由结构自动生成的专属类型文件，里面包含了匹配你项目实际页面的Href类型。而GitHub Actions环境中，因为没有运行过Expo的启动或构建命令，.expo目录不存在（该目录默认被.gitignore忽略，不会同步到仓库），TypeScript只能读取expo-router包本身的默认类型定义，但在SDK49对应的Expo Router v2版本中，Href并不是顶层导出成员，因此CI环境会报错。

.expo目录的作用与默认忽略原因 #

作用 #

• 存储Expo运行时自动生成的文件：包括路由类型定义、项目缓存、构建配置快照、开发环境临时配置（如设备连接信息、开发服务器端口）等。
• 基于本地项目状态动态生成，用于优化开发体验，比如让TypeScript识别你自定义的路由路径。

默认忽略原因 #

• 属于环境绑定的临时产物：不同开发者的本地环境、项目运行状态不同，生成的.expo内容也会有差异，不需要提交到Git仓库。
• 可重复生成：重新运行expo start或构建命令时，Expo会自动重新生成该目录下的必要文件，无需手动维护。
• 避免仓库膨胀与冲突：减少不必要的文件提交，避免因环境差异导致的Git版本冲突。

统一本地与CI环境的解决方案 #

方案1：在CI中先生成类型文件 #

在GitHub Actions的执行脚本中，先添加生成.expo类型文件的步骤，再执行类型检查：

# 生成路由类型文件，无需启动开发服务器
expo prebuild --no-install
# 执行类型检查
tsc --noEmit --pretty

这样CI环境会生成和本地一致的路由类型文件，消除类型检查差异。

方案2：引用本地生成的路由类型 #

避免直接从expo-router导入Href，改为引用本地自动生成的类型：

import { Link } from "expo-router";
// 引用项目专属的Href类型
type AppHref = import(".expo/types/router").Href;

// 在组件中使用
const CustomLink = ({ href }: { href: AppHref }) => {
  return <Link href={href}>跳转</Link>;
};

同时确保tsconfig.json包含.expo目录的类型文件：

{
  "include": [
    ".expo/types/**/*.d.ts",
    "**/*.ts",
    "**/*.tsx"
  ]
}

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