Next.js 配置 pageExtensions

// packages/next/src/server/config-shared.ts
export const defaultConfig = {
  ...
  pageExtensions: ['tsx', 'ts', 'jsx', 'js'],  // pageExtensions 默认值
  ...
}

// packages/next/src/server/config-shared.ts
export async function normalizeConfig(phase: string, config: any) {
  if (typeof config === 'function') {
    config = config(phase, { defaultConfig })
  }
  // Support `new Promise` and `async () =>` as return values of the config export
  return await config
}

// packages/next/src/server/config.ts
const loadedConfig = Object.freeze(
  (await normalizeConfig(
    phase,
    interopDefault(userConfigModule)
  )) as NextConfig
)

export async function getStaticInfoIncludingLayouts({
  isInsideAppDir,
  pageExtensions,
  pageFilePath,
  appDir,
  config: nextConfig,
  isDev,
  page,
}: {
  isInsideAppDir: boolean
  pageExtensions: PageExtensions
  pageFilePath: string
  appDir: string | undefined
  config: NextConfigComplete
  isDev: boolean | undefined
  page: string
}): Promise<PageStaticInfo> {
  ...

  // inherit from layout files only if it's a page route
  if (isAppPageRoute(page)) {
    const layoutFiles = []
    const potentialLayoutFiles = pageExtensions.map((ext) => 'layout.' + ext)
    // 这里将扩展名映射为了可以支持的 layout.[ext] 文件名，例如配置tsx，jsx；那么这个集合包含了「layout.tsx, layout.jsx」
    let dir = dirname(pageFilePath)

    ...
}

/**
 * Calculate all possible pagePaths for a given normalized pagePath along with
 * allowed extensions. This can be used to check which one of the files exists
 * and to debug inspected locations.
 *
 * For pages, map `/route` to [`/route.[ext]`, `/route/index.[ext]`]
 * For app paths, map `/route/page` to [`/route/page.[ext]`] or `/route/route`
 * to [`/route/route.[ext]`]
 *
 * @param normalizedPagePath Normalized page path (it will denormalize).
 * @param extensions Allowed extensions.
 */
export function getPagePaths(
  normalizedPagePath: string,
  extensions: string[],
  isAppDir: boolean
) {
  const page = denormalizePagePath(normalizedPagePath)

  let prefixes: string[]
  // 两种路由模式不同的处理
  /*
  *如果是 app 目录，只用 page 本身作为前缀。
  *如果是 pages 目录且路径以 /index 结尾，只用 page/index 作为前缀。
  *否则，既用 page 也用 page/index 作为前缀。
  */
  if (isAppDir) {
    prefixes = [page]
  } else if (normalizedPagePath.endsWith('/index')) {
    prefixes = [path.join(page, 'index')]
  } else {
    prefixes = [page, path.join(page, 'index')]
  }

  const paths: string[] = []
  for (const extension of extensions) {
    for (const prefix of prefixes) {
      paths.push(`${prefix}.${extension}`)
    }
  }

  // ⬆️这里最后会返回包含符合pageExtensions的可能存在的页面路径数组
  return paths
}

/**
 * Finds a page file with the given parameters. If the page is duplicated with
 * multiple extensions it will throw, otherwise it will return the *relative*
 * path to the page file or null if it is not found.
 *
 * @param pagesDir Absolute path to the pages folder with trailing `/pages`.
 * @param normalizedPagePath The page normalized (it will be denormalized).
 * @param pageExtensions Array of page extensions.
 */
export async function findPageFile(
  pagesDir: string,
  normalizedPagePath: string,
  pageExtensions: PageExtensions,
  isAppDir: boolean
): Promise<string | null> {
  // 第一步这里拿到的就是 1.4.3 最后返回的符合 pageExtensions 的可能存在页面组件路径
  const pagePaths = getPagePaths(normalizedPagePath, pageExtensions, isAppDir)

  // 这里的判空逻辑蛮优雅的，数组解构拿到了第一项，然后下面都是一系列的验证这个可能路径上的文件是否存在，当然如果存在的话，就是页面组件了
  const [existingPath, ...others] = (
    await Promise.all(
      pagePaths.map(async (path) => {
        const filePath = join(pagesDir, path)
        try {
          return (await fileExists(filePath)) ? path : null
        } catch (err: any) {
          if (!err?.code?.includes('ENOTDIR')) throw err
        }
        return null
      })
    )
  ).filter(nonNullable)

  if (!existingPath) {
    return null
  }

  if (!(await isTrueCasePagePath(existingPath, pagesDir))) {
    return null
  }

  // 在上面，我们已经排空了，那么如果同一目录下，如果出现多个pageExtensions支持的页面组件文件，
  // 例如：同文件夹下存在「page.tsx, page.jsx」，那么，nextjs会直接报出下面的警告，「会有两个文件被解析成同一个路由」。
  if (others.length > 0) {
    warn(
      `Duplicate page detected. ${cyan(join('pages', existingPath))} and ${cyan(
        join('pages', others[0])
      )} both resolve to ${cyan(normalizedPagePath)}.`
    )
  }

  return existingPath
}

// packages/next/src/lib/metadata/is-metadata-route.ts
/**
 * Determine if the file is a metadata route file entry
 * @param appDirRelativePath the relative file path to app/
 * @param pageExtensions the js extensions, such as ['js', 'jsx', 'ts', 'tsx']
 * @param strictlyMatchExtensions if it's true, match the file with page extension, otherwise match the file with default corresponding extension
 * @returns if the file is a metadata route file
 */
export function isMetadataRouteFile(
  appDirRelativePath: string,
  pageExtensions: PageExtensions,
  strictlyMatchExtensions: boolean
) {
  // End with the extension or optional to have the extension
  // When strictlyMatchExtensions is true, it's used for match file path;
  // When strictlyMatchExtensions, the dynamic extension is skipped but
  // static extension is kept, which is usually used for matching route path.
  const trailingMatcher = (strictlyMatchExtensions ? '' : '?') + '$'
  // Match the optional variants like /opengraph-image2, /icon-a102f4.png, etc.
  const variantsMatcher = '\\d?'
  // The -\w{6} is the suffix that normalized from group routes;
  const groupSuffix = strictlyMatchExtensions ? '' : '(-\\w{6})?'

  const suffixMatcher = `${variantsMatcher}${groupSuffix}`

  // 这里生成一些元数据路由文件扩展名与 pageExtensions 中的扩展名的正则集合
  const metadataRouteFilesRegex = [
    new RegExp(
      `^[\\\\/]robots${getExtensionRegexString(
        pageExtensions.concat('txt'),
        null
      )}${trailingMatcher}`
    ),
    new RegExp(
      `[\\\\/]${STATIC_METADATA_IMAGES.twitter.filename}${suffixMatcher}${getExtensionRegexString(
        STATIC_METADATA_IMAGES.twitter.extensions,
        pageExtensions
      )}${trailingMatcher}`
    ),
    ...
  ]

  const normalizedAppDirRelativePath = normalizePathSep(appDirRelativePath)

  const matched = metadataRouteFilesRegex.some((r) =>
    r.test(normalizedAppDirRelativePath)
  )
  // 最后得到的 matched 就是匹配成功的元数据路由文件
  return matched
}