GitHub 特殊仓库名称：同名仓库、.github.io 与 .github

仓库名称通常只是路径标识，但 GitHub 上有几类名称会被平台本身赋予额外含义：与用户名完全同名的仓库会出现在个人主页，叫 <用户名>.github.io 的仓库会开通用户站点，组织或账号下名为 .github 的仓库会给全账号仓库提供默认社区健康文件。这些能力主要按名称触发，多数还要求仓库公开，不需要申请，也没有付费开关。本文按这三个仓库逐条给出规则、创建步骤、生效确认和故障处理，最后汇总仓库内部的特殊目录与文件名。

Pages 的发布源、自定义域名等完整流程已另有 GitHub Pages 使用教程，Actions 工作流见 GitHub Actions 使用教程，本文不重复展开。

三类特殊仓库速查

仓库名称	适用的账号	触发的功能	硬性条件
<用户名>	个人账号	个人资料页顶部的 Profile README	与用户名完全同名、公开、每账号一个
<用户名>.github.io	个人或组织账号	GitHub Pages 用户/组织站点	名称全小写匹配、发布源为所选分支目录或 Actions
.github	组织或个人账号	账号下所有仓库的默认社区健康文件	名称精确为 .github、公开

三个仓库都是普通仓库：可以继续存放代码、Issue 和 Releases，特殊之处只在于名称命中了平台的识别规则。

前置条件

• 一个 GitHub 账号；组织场景需要组织 Owner 或具备创建仓库权限的管理员身份。
• 理解仓库名称与访问地址的关系：仓库地址是 https://github.com/<所有者>/<仓库名>，所有者为用户名或组织名。GitHub 入门教程说明了账号、仓库与协作的基本概念。
• 只在这些仓库中放愿意公开的内容：仓库一旦公开，README、历史提交和文件都会被搜索引擎抓取，删除文件不等于撤回。

Profile README：与用户名同名的仓库

登录 GitHub 后打开 https://github.com/<你的用户名>，个人资料页顶部会出现一个 README 卡片区域。按管理个人资料自述文件的规则，仓库满足以下四个条件时，README 会渲染在该区域：

1. 仓库名与用户名完全相同，每个账号只有这一个资格仓库；
2. 仓库可见性为 Public，转私有后展示立即消失；
3. README.md 位于仓库根目录，放在 .github 等子目录中不会被识别；
4. README 有实际内容，清空文件同样会让卡片消失。

创建步骤

1. 打开自己的资料页，单击顶部 README 区域的 Add README…；没有该入口时，手动新建仓库，仓库名填 <你的用户名>，可见性选 Public，勾选 Add a README file，点击 Create repository。
2. 编辑根目录的 README.md，GitHub 会预填一个起始模板，改成自己的介绍后提交。
3. 回到 https://github.com/<你的用户名> 刷新。

成功信号：资料页顶部出现渲染出的 README 卡片；仓库本体仍可通过 https://github.com/<你的用户名>/<你的用户名> 正常访问。

写什么、社区怎么写

一个被广泛采用的结构是：一句话自我定位、当前在做的 1-2 个项目、技术栈、联系方式或博客链接。第三方动态组件（访问计数、徽章、统计图）都是外部服务生成的图片，装饰性强，注意服务可用性与隐私边界。三个广泛使用的社区项目：

项目	定位	用法
abhisheknaiidu/awesome-github-profile-readme	精选 Profile README 实例合集，实时更新	找灵感、对照别人的信息密度
rahuldkjain/github-profile-readme-generator	网页表单生成 Markdown	勾选模块后一键复制内容，粘贴进 README 提交
lowlighter/metrics	用 GitHub Actions 定期生成统计信息图	在同名仓库配置工作流，把渲染出的 SVG 嵌入 README

github-profile-readme 话题页还有更多生成器和组件可供检索。需要注意边界：外部服务停服后，徽章与统计图会在资料页顶部留下一排失效图片，核心信息仍应由 README 的静态文字承担。

改名后的行为

更改用户名后，旧的 <旧用户名> 仓库不再满足同名条件，Profile README 会停止展示；旧用户名会被立即释放并开放重新注册，仓库链接通过重定向指向新路径，一旦有人注册旧用户名并建立同名仓库，重定向即被覆盖（用户名更改）。因此改名后需要新建一个与 <新用户名> 同名的仓库并迁移内容。

<用户名>.github.io：Pages 用户站点仓库

仓库名精确等于 <用户名或组织名>.github.io 时，GitHub Pages 会按用户站点处理，默认地址为 https://<用户名>.github.io/，每个个人账号或组织一个，适合个人主页、作品集和博客。名称包含大写字母时，仓库名中的所有者部分必须转成小写（创建 GitHub Pages 站点）。组织站点规则完全相同，地址为 https://<组织名>.github.io/。

最快发布路径

1. 在账号下新建公开仓库，仓库名精确填 <你的用户名>.github.io，勾选初始化 README。
2. 放入一个 index.html（网页 Add file 或 git push 均可），到 Settings → Pages 把发布源选为默认分支的根目录（/(root)）并保存。

要点：

• 与项目站点（https://<用户名>.github.io/<仓库名>/）相比，用户站点没有仓库名这一层路径，静态站生成器的 base、资源绝对路径都按根路径书写。
• 在用户名下新建一个仓库名叫 xxx.github.io 的仓库，只会得到一个普通项目站点 https://<用户名>.github.io/xxx.github.io/，不会开通第二个用户站点。
• 发布源仍是 Pages 设置里的分支目录或 GitHub Actions，特殊名称只决定"站点挂在用户站点位置"，不改变发布机制；框架构建、Actions 部署等完整流程见 Pages 使用教程。
• 想绑定自己的域名时，需要同时在域名解析和仓库 Pages 设置中登记，任一缺失都会导致域名打不开站点；完整步骤见 Pages 使用教程的自定义域名一节。

生效确认：仓库 Settings → Pages 显示的访问地址不带仓库名路径，浏览器打开后看到默认分支根目录（或所选目录）的入口文件。

.github.io 仓库依然是公开仓库，简历、头像目录、站点源码里的所有文件都在公网可检索范围内，令牌、私有项目草稿不要放在其中。

路径冲突：用户站点与项目站点

用户站点和项目站点共用同一个一级路径命名空间：开启了 Pages 的项目仓库会占用 https://<用户名>.github.io/<仓库名>/ 下的全部路径。用户站点里若存在同名目录，项目站点优先，用户站点的该路径被整体遮蔽，两边内容不会合并（Stack Overflow 上的实测与 GitHub 支持答复）。GitHub 支持在该问题的转引答复中建议的解法就是重命名目录或重命名仓库，按成本从低到高排列：

1. 改用户站点目录：把内容挪去一个不冲突的一级名，同步更新站内链接与生成器的 base。
2. 改项目仓库名：仓库名即 URL slug，站点随之迁移到新路径；旧路径仍会产生改名重定向，不能假定冲突自动消失，引用 /旧仓库名/ 的外链和 base 需要一并更新。
3. 给项目站点绑自定义域名：主要访问入口迁到自定义域名；/<仓库名>/ 路径是否同步释放给用户站点未经实测，指望彻底腾出命名空间时优先用前两种改法。

规划上建议把用户站点的一级目录（如 /blog/、/tools/）当作保留字管理：新建会开 Pages 的仓库前，先确认用户站点没有同名目录，反向同理。

.github：默认社区健康文件仓库

组织或个人账号下名为 .github 的公开仓库，是默认社区健康文件的存放位置。该机制要解决的问题是：组织内几十上百个仓库，逐个维护 CONTRIBUTING.md、SECURITY.md 和 Issue 模板成本太高，集中一份即可全账号生效。

• 支持的文件包括贡献指南（CONTRIBUTING.md）、行为准则（CODE_OF_CONDUCT.md）、安全政策（SECURITY.md）、支持指南（SUPPORT.md）、资金方案（FUNDING.yml）、Issue 与 Pull Request 模板（ISSUE_TEMPLATE/、PULL_REQUEST_TEMPLATE.md）、讨论表单（DISCUSSION_TEMPLATE/）。许可证文件不在支持列表内。
• 生效优先级是"本地优先、全局兜底"：GitHub 先在目标仓库自身的 .github/ 目录、根目录和 docs/ 目录查找对应文件，全部没有时才使用 .github 仓库中的默认版本。仓库自己放一份就能覆盖组织默认值。
• 默认文件不会出现在账号下各仓库的文件浏览器或 Git 历史中；成员仓库想要一份自己的副本，需要在仓库内显式创建。
• 组织级默认文件 2019 年上线（GitHub Changelog），现在个人账号同样适用。

组织配置步骤

1. 在组织下新建公开仓库，名称精确填 .github。
2. 按需要把 SECURITY.md、CODE_OF_CONDUCT.md、CONTRIBUTING.md、FUNDING.yml 放在该仓库根目录，或把模板放入 .github/ISSUE_TEMPLATE/ 等目录——.github 仓库自身的布局同样遵循"本地查找"规则。
3. 打开组织内任意未提供同名文件的仓库，在仓库首页的 Community 面板核对健康文件清单是否指向 .github 仓库。

默认文件生效的表现：目标仓库的 Security 标签页出现指向 .github 仓库的安全政策链接；新建 Issue 页面提供的模板来自 .github 仓库；仓库首页显示组织级 CONTRIBUTING 链接。

公开实践可以参考 github/.github 和 microsoft/.github：两个组织都把安全政策、行为准则和 Issue 模板集中在这一个仓库里，各成员仓库不再单独维护。写组织自己的 .github 时建议只保留一份权威文件，避免同时在成员仓库放旧副本——本地副本会静默覆盖默认值，是最难排查的一类"改了没生效"。

仓库内部的特殊目录与文件名

仓库名之外，一批固定的目录和文件名会在单个仓库内触发功能，GitHub 主要在默认分支上查找：

名称	支持的位置	功能
.github/workflows/	仅该目录	GitHub Actions 工作流定义
.github/ISSUE_TEMPLATE/	仅该目录	Issue 模板；config.yml 控制模板选择页；文件名加数字前缀控制顺序，YAML 表单按字母序排在 Markdown 模板之前
.github/DISCUSSION_TEMPLATE/	仅该目录	Discussions 分类表单
PULL_REQUEST_TEMPLATE.md	根目录、.github/、docs/	新建 PR 时预填正文
SECURITY.md	根目录、.github/、docs/	在 Security 标签页展示安全政策与漏洞报告方式
FUNDING.yml	.github/FUNDING.yml	仓库首页 Sponsor 按钮；github、patreon、custom 等键对应不同筹资渠道
CODEOWNERS	根目录、.github/、docs/	声明代码责任人，PR 改动命中路径时自动请求 review

几个容易踩空的硬性细节：Issue 模板的标识符必须超过三个字符才会渲染（配置 Issue 模板）；FUNDING.yml 生效还需在仓库 Settings → General → Features 勾选 Sponsorships（展示赞助按钮）；CODEOWNERS 按 .github/、根目录、docs/ 的顺序搜索第一个命中的文件，被列名的成员需要对该仓库有写入权限，"合并前必须获得 owner 批准"则要靠分支保护规则开启（关于 CODEOWNERS）。

权限与计费边界

• 三类特殊仓库的触发功能都依赖公开访问：Profile README 和 .github 默认文件硬性要求公开；Pages 站点的仓库可见性则取决于方案，GitHub Free 只能发布公开仓库，私有发布与站点访问控制受方案限制，见 Pages 教程的计费说明。
• Profile README 与 .github.io 站点仓库由账号所有者直接创建，不涉及额外权限。组织的 .github 仓库建议限制写权限到管理员：里面的模板笔误会同时出现在全组织的 Issue 页面上。
• 同名仓库每个账号只有一个，.github.io 用户站点同样只有一个；把示例代码、学习笔记塞进这两个仓库，等于让此类内容与站点源码、个人介绍永久同仓，规划时提前想清楚。

常见故障处理

现象	排查顺序
资料页不显示 Profile README	依次核对四个条件：仓库名与用户名完全一致；可见性为 Public；README.md 在根目录而非子目录；文件非空。功能上线（2020 年 7 月）前创建的同名旧仓库不会自动激活，仓库 README 页面会出现 Share to profile 提示，点击后手动共享到资料页
Pages 报"站名不匹配"或站点 404	仓库名是否为全小写的 <用户名>.github.io（所有者含大写字母时必须转小写）；发布源分支是否已配置；仓库 Settings → Pages 显示的地址才是权威地址
用户站点某个一级目录打开后是项目站点内容或 404	是否新建了同名且开启 Pages 的项目仓库——项目站点优先占用 /<仓库名>/，用户站点同名路径被遮蔽；按上文"路径冲突"一节处理
.github 仓库改了文件，成员仓库没变化	成员仓库自身是否放了同名文件——本地文件优先，默认值只在缺失时兜底；确认文件在默认分支
Sponsor 按钮不出现	路径必须是 .github/FUNDING.yml（不是根目录）；Settings → General 的 Sponsorships 是否勾选；键名拼写是否属于支持的平台列表
CODEOWNERS 不请求 review	文件是否位于根目录、.github/ 或 docs/；被列名用户是否有仓库写入权限；路径大小写是否精确匹配；要求批准后才能合并需另行开启分支保护
Issue 模板不生效	模板是否位于 .github/ISSUE_TEMPLATE/ 而非根目录；模板标识是否超过三个字符；config.yml 是否误配了"禁用空白 Issue 并全部外链"

参考资料

官方文档：

1. Managing your profile README——Profile README 四条件与创建入口。
2. Creating a GitHub Pages site——用户/组织站点命名与小写规则。
3. Creating a default community health file——.github 仓库支持的文件清单与本地优先顺序。
4. Username changes——改名后的重定向与旧用户名释放。
5. Adding a security policy to your repository——SECURITY.md 在 Security 标签页的呈现。
6. Displaying a sponsor button——FUNDING.yml 路径、平台键与 Sponsorships 开关。
7. About code owners——CODEOWNERS 位置顺序、权限与 review 请求。
8. Configuring issue templates——模板目录、config.yml 与排序规则。
9. Creating discussion category forms——DISCUSSION_TEMPLATE 目录。
10. Organization-wide community health files——组织级默认文件上线公告。
11. Changing the visibility of your GitHub Pages site——私有发布与访问控制的方案归属。

社区实践：

12. abhisheknaiidu/awesome-github-profile-readme
13. rahuldkjain/github-profile-readme-generator
14. lowlighter/metrics
15. github/.github 与 microsoft/.github
16. github-profile-readme 话题页
17. Does a folder in my user site conflict with a project site?——含 GitHub 支持答复与社区实测的用户站点/项目站点路径冲突讨论。

站内相关：GitHub Pages 使用教程、gh-pages 分支使用教程、GitHub Actions 使用教程、GitHub 入门。