机器翻译正文由机器翻译自项目原始文档（英文），排版经程序统一处理，可能存在偏差，请以原项目仓库为准。

螺丝固定

ScrewFast 是一个开源网站模板，使用 Astro、Tailwind CSS 和 Preline UI 构建。你可以在一个仓库中获取登陆页面、博客、产品页面和完整的文档站点，因此只需编辑内容和属性即可上线完整网站，而无需从零构建页面。与单一用途的登陆页或博客主题不同，它内置了 SEO 元数据、多语言支持、安全头信息和 CI 配置。

Live demo: screwfast.uk

• 四合一网站类型。 登陆页面、博客、产品目录和 Starlight 文档，共用同一布局、导航栏和页脚。
• 现成组件。 页面部分（英雄区、功能、价格、客户评价、FAQ、大型菜单）和 UI 元件（卡片、表单、模态框、按钮、图标）。
• 开箱即用的多语言。 英文和法文营销页面；文档支持 7 种语言（en, de, es, fa, fr, ja, zh-CN）并支持 RTL。如果只需要一种语言？使用 monolingual-site 分支。
• SEO 已处理。 集中配置标题/描述/Open Graph、JSON-LD 结构化数据、生成网站地图和 robots.txt 。
• 生产环境强化。 通过 vercel.json 设置内容安全策略和其他安全头信息，构建后 HTML 压缩，以及 CI 流水线对每次推送进行类型检查、构建和冒烟测试。
• 当前栈。 Astro 7、Tailwind CSS 4、Preline 5、TypeScript 6。Dependabot 保持依赖更新。
• AI 助手友好。 AI_GUIDE.md 告诉 Cursor、Copilot 和 Claude 组件位置及遵循的约定。
• MIT 许可。 GitHub 上有 1.4k 星标和 380 个分支。

页面由带有普通属性的各部分组成：

---
import MainLayout from '@/layouts/MainLayout.astro';
import HeroSection from '@components/sections/landing/HeroSection.astro';
---

<MainLayout title="Acme Tools">
  <HeroSection
    title="Equip Your Projects with Acme"
    subTitle="Top-quality hardware tools for every project need."
    primaryBtn="Start Exploring"
    primaryBtnURL="/products"
  />
</MainLayout>
<!-- Renders a full page with navbar, hero, and footer -->

入门指南

你需要 Node.js 22 和 pnpm 9 或更高版本（CI 使用的版本）。

1. 创建你的仓库。 点击 GitHub 页面 顶部的 使用此模板，或直接克隆：

git clone https://github.com/mearashadowfax/ScrewFast.git my-site
cd my-site

2. 安装依赖项：

pnpm install

3. 启动开发服务器：

pnpm dev

打开 http://localhost:4321。对任何文件的编辑都会重新加载页面。

4. 构建生产版本：

pnpm build

这会运行 astro check（类型检查）、将网站构建到 dist/，并压缩 HTML。使用 pnpm preview 预览结果，或运行 pnpm test:smoke 来服务 dist/ 并验证关键路由的响应。

让它成为你的

网站名称、SEO 和开放图谱

整个网站的内容都在 src/data_files/constants.ts 中：

export const SITE = {
  title: 'ScrewFast',
  tagline: 'Top-quality Hardware Tools',
  description: '...',
  url: 'https://screwfast.uk',
  author: 'Emil Gulamov',
};

export const OG = { image: ogImageSrc };

每个区域的文本（网站描述、Open Graph 标题/描述）位于 src/copy/ 下的文案表中。更改 SITE，所有页面的 <head> 都会自动更新。同时在 astro.config.mjs 中更新 site，以便网站地图和 robots.txt 指向你的域名。

导航和页脚

链接结构（ID、非本地化路径、社交网址）存放在 src/data_files/navigation.ts ；每个 ID 的标签位于每个文案表的 nav 块中， src/copy/en.ts 和 src/copy/fr.ts 。当前区域的导航栏和页脚前缀路径：

// src/data_files/navigation.ts
export const navLinks = [
  { id: 'home', path: '/' },
  { id: 'products', path: '/products' },
  { id: 'blog', path: '/blog' },
];
export const footerSections = [
  { id: 'company', links: [{ id: 'careers', path: '#', badge: 'hiring' }] },
];

// src/copy/en.ts
nav: {
  labels: { home: 'Home', products: 'Products', blog: 'Blog' },
  footer: { sectionTitles: { company: 'Company' }, links: { careers: 'Careers' } },
},

src/components/sections/navbar&footer/ 中包含两个导航栏：Navbar.astro（标准）和 NavbarMegaMenu.astro（服务链接上的巨型菜单，链接在 src/data_files/mega_link.ts 中）。在 src/layouts/MainLayout.astro 中交换它们。

页面和部分

每个路由在 src/views/ 中都有一个视图（例如 HomeView.astro），该视图由 src/components/sections/ 的部分组成，并将内容作为属性传递。src/pages/ 和 src/pages/fr/ 中的文件是单行的壳文件，用于渲染其语言环境的视图，因此每种语言只需编辑一次页面。

视图从 src/copy/ 的文案表中读取文本（home，services，contact，…）；编辑这些表即可更改页面内容。可重用的数据，如常见问题、功能和定价等级，以 JSON 形式存放在 src/data_files/ 中，并通过与 data 相同的表进行暴露。

博客、产品和见解

内容以 Markdown/MDX 形式存放在 src/content/{blog,products,insights}/{en,fr}/ 中。架构定义在 src/content.config.ts 中。一篇博客文章的示例如下：

---
title: "Maximizing Efficiency with ScrewFast's Cutting-Edge Tools"
description: 'Innovating Construction Efficiency with Precision Tools & Support'
author: 'Jacob'
authorImage: '@/images/blog/jacob.avif'
pubDate: 2024-02-06
cardImage: '@/images/blog/post-1.avif'
readTime: 4
tags: ['tools', 'construction', 'workflow']
---

Post body here.

博客文章将获得社交分享按钮、一个 localStorage 收藏按钮以及一个反馈小部件（仅 UI，无后端）。洞察页面会显示带有滚动进度指示器的目录。

文档（Starlight）

文档存放在 src/content/docs/ 中，由 Starlight 在 /welcome-to-docs/ 提供服务。侧边栏、本地化及自定义组件在 astro.config.mjs 的 starlight() 模块中配置。Starlight 提供搜索、深色模式、代码高亮和响应式导航功能。

语言

营销页面基于文件：src/pages/ 为英语，src/pages/fr/ 为法语，每个页面渲染自 src/views/ 的共享视图。一个 LanguagePicker 组件用于在它们之间切换。所有与本地化相关的内容位于 src/utils/locale.ts （本地化列表、resolveLocale()、localePath()、alternatePaths()）；中间件在每次请求时解析本地化，并将其作为 Astro.locals.locale 暴露，匹配的文案表为 Astro.locals.copy。UI 字符串位于 src/copy/en.ts 和 src/copy/fr.ts ；法语表会与英语表进行类型匹配，因此缺失翻译会导致 astro check 失败。文档的本地化在 Starlight 中配置；指南和欢迎页面翻译完成，其他文档部分回退到英语。

静态构建只能有一个 404.html（英语）。法语 404 页面也在 /fr/404/ 构建； vercel.json 中的 rewrites 条目将缺失的 /fr/… 路径发送到该页面（Vercel 使用 200 状态提供重写）。在 Netlify 上使用 _redirects 行替代：/fr/* /fr/404/index.html 404。

图标

SVG 图标集中在 src/components/ui/icons/icons.ts （包含 45 个）。使用以下方法渲染：

<Icon name="tools" class="h-6 w-6 text-orange-400" />

条目只包含几何信息；大小和颜色来自你传入的 class（每个图标都用 text-* 类着色）。name 是有类型的，所以拼写错误会导致 astro check 失败。向 icons.ts 添加一个条目以注册新图标。

部署

pnpm build 在 dist/ 中生成一个静态站点，任何静态托管服务都可以提供该站点。

• Vercel： 使用 Vercel 部署。附带的 vercel.json 添加了安全头和缓存规则。
• Netlify: Deploy to Netlify.

项目结构

src/
├── assets/
│   ├── scripts/            # Lenis smooth scroll, demo form behaviour
│   └── styles/             # global.css, lenis.css, Starlight overrides
├── components/
│   ├── Meta.astro          # Renders the <head> from utils/metadata.ts
│   ├── ThemeIcon.astro     # Light/dark toggle
│   ├── sections/           # Page sections: landing, features, pricing, navbar&footer, ...
│   └── ui/                 # Buttons, cards, forms, icons, banners, ...
├── content/
│   ├── blog/  products/  insights/   # en/ and fr/ subfolders
│   └── docs/                          # Starlight docs + translated locales
├── copy/                   # en.ts / fr.ts: every UI and page string, typed
├── data_files/             # constants.ts (SITE/OG), navigation.ts, mega_link.ts, faqs/features/pricing JSON
├── images/                 # Imported and optimized by Astro
├── layouts/
│   └── MainLayout.astro    # Navbar + slot + footer, Meta, Lenis, Preline
├── middleware.ts           # Sets Astro.locals.locale / .copy per request
├── pages/                  # File-based routes; fr/ mirrors them, each a one-line shell
│   ├── index.astro  blog/  products/  insights/  contact.astro  services.astro
│   ├── 404.astro           # also built at fr/404/
│   └── robots.txt.ts  manifest.json.ts  favicon.ico.ts
├── views/                  # One view per route; the locale is a prop
├── utils/                  # locale.ts, content.ts, metadata.ts, helpers
└── content.config.ts       # Content collection schemas

public/                     # Served as-is
process-html.mjs            # Post-build HTML minifier
scripts/smoke.mjs           # Serves dist/ and checks every marketing route in both locales
vercel.json                 # Security headers and caching
AI_GUIDE.md                 # Conventions for AI coding assistants

路径别名（@components/*，@content/*，@data/*，@images/*，@scripts/*，@styles/*，@utils/*，@views/*，@/*）定义在tsconfig.json中。

引擎核心

平滑滚动（Lenis）

Lenis 已从 src/assets/scripts/lenisSmoothScroll.js 加载到 MainLayout.astro 和 src/components/ui/starlight/Head.astro 中。平滑滚动可能会影响某些设备上的可访问性和性能，因此请针对您的受众进行测试。

要恢复原生滚动，请从两个文件中删除此内容：

<script>
  import '@scripts/lenisSmoothScroll.js';
</script>

动画（GSAP）

GSAP 在加载时为产品和洞察详情页面添加动画。设置位于 src/components/sections/products/ProductDetail.astro 和 src/components/sections/insights/InsightDetail.astro 的 <script> 区块中。可以调整 gsap.from() 调用，或删除脚本区块以移除 GSAP。

隐藏滚动条

为了更清爽的外观，滚动条被隐藏。这可能会影响部分用户的可用性；要恢复它，请从 MainLayout.astro 中的 <html> 移除 scrollbar-hide 类，并删除该文件底部的 .scrollbar-hide 样式。对于自定义样式滚动条，tailwind-scrollbar 是一个不错的选择。

SEO 和结构化数据

页面告诉 MainLayout 它的身份（title、description、section、kind）；src/utils/metadata.ts 将其转换为完整的 <head>：带站点后缀的标题、描述、Open Graph 和 Twitter 标签（title | section | site）、规范链接、hreflang 替代项，以及填充网站模板的 schema.org JSON-LD。语言区域由中间件通过 URL 获取，因此页面从不手动传递，也不手动编写 schema.org 对象：

<MainLayout
  title="Example Page"
  description="What this page is about."
  section="Insights"
  kind={{ type: 'Article', image: post.data.cardImage.src }}
>
  ...
</MainLayout>

kind 是 WebPage（默认）、BlogPosting、Article 或 Product。可在 metadata.ts 中添加新类型，或在 Meta.astro 中添加额外标签。

表单

联系表单、新闻通讯表单以及登录/注册/找回表单是放置在 DemoForm.astro 中的占位符，它会拦截提交、验证、显示每种语言的成功消息并重置。要连接真实的后端，请将 <DemoForm> 包装器替换为 <form action=…>（或您提供者的片段），并移除 successMessage；其中的输入字段为普通 HTML 字段。

robots.txt 与站点地图

src/pages/robots.txt.ts 在构建时生成 robots.txt，并链接到由 @astrojs/sitemap 生成的站点地图。两者都从 astro.config.mjs 中的 site 获取域名。

Markdown、MDX 以及图片粘贴

@astrojs/mdx 已启用，因此内容文件可以是 .md 或 .mdx。包含的 .vscode/settings.json 允许您在按住 Shift 时，将图片粘贴或拖入内容文件：VS Code 会将其复制到 src/images/content/<file-name>/ 并插入 Markdown 链接。

HTML 压缩

pnpm build 最后会运行 process-html.mjs，使用 html-minifier-terser 来压缩构建输出中的每个 HTML 文件。

安全头

vercel.json 设置 Content-Security-Policy、X-Frame-Options、X-Content-Type-Options、Referrer-Policy、Permissions-Policy 以及缓存头。如果添加第三方脚本或图片托管，请调整 CSP。

格式化

使用 prettier-plugin-astro 和 prettier-plugin-tailwindcss（类排序）的 Prettier 已在 .prettierrc 中配置。可在本地运行 pnpm format:fix；CI 将运行 pnpm format:check。

贡献

• 错误和想法： 打开一个 issue 或开始一个 讨论。
• 拉取请求： 欢迎。在提交之前运行 pnpm format:fix 和 pnpm build。

See CODE_OF_CONDUCT.md.

许可

MIT. See LICENSE.

显示的公司、产品和标志是虚构的或仅用于演示，应在您的网站中替换。